7Internet Engineering Task Force (IETF) B. Leiba
8Request for Comments: 6154 Huawei Technologies
9Category: Standards Track J. Nicolson
14 IMAP LIST Extension for Special-Use Mailboxes
18 Some IMAP message stores include special-use mailboxes, such as those
19 used to hold draft messages or sent messages. Many mail clients
20 allow users to specify where draft or sent messages should be put,
21 but configuring them requires that the user know which mailboxes the
22 server has set aside for these purposes. This extension adds new
23 optional mailbox attributes that a server may include in IMAP LIST
24 command responses to identify special-use mailboxes to the client,
29 This is an Internet Standards Track document.
31 This document is a product of the Internet Engineering Task Force
32 (IETF). It represents the consensus of the IETF community. It has
33 received public review and has been approved for publication by the
34 Internet Engineering Steering Group (IESG). Further information on
35 Internet Standards is available in Section 2 of RFC 5741.
37 Information about the current status of this document, any errata,
38 and how to provide feedback on it may be obtained at
39 http://www.rfc-editor.org/info/rfc6154.
43 Copyright (c) 2011 IETF Trust and the persons identified as the
44 document authors. All rights reserved.
46 This document is subject to BCP 78 and the IETF Trust's Legal
47 Provisions Relating to IETF Documents
48 (http://trustee.ietf.org/license-info) in effect on the date of
49 publication of this document. Please review these documents
50 carefully, as they describe your rights and restrictions with respect
51 to this document. Code Components extracted from this document must
52 include Simplified BSD License text as described in Section 4.e of
53 the Trust Legal Provisions and are provided without warranty as
54 described in the Simplified BSD License.
58Leiba & Nicolson Standards Track [Page 1]
60RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
66 1.1. Conventions Used in This Document . . . . . . . . . . . . 3
67 2. New Mailbox Attributes Identifying Special-Use Mailboxes . . . 3
68 3. Extension to IMAP CREATE Command to Set Special-Use
69 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 5
70 4. IMAP METADATA Entry for Special-Use Attributes . . . . . . . . 6
71 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
72 5.1. Example of an IMAP LIST Command . . . . . . . . . . . . . 7
73 5.2. Example of an Extended IMAP LIST Command . . . . . . . . . 7
74 5.3. Example of an IMAP CREATE Command . . . . . . . . . . . . 8
75 5.4. Example of Using IMAP METADATA to Manipulate
76 Special-Use Attributes . . . . . . . . . . . . . . . . . . 8
77 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9
78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
80 8.1. Registration of USEATTR IMAP Response Code . . . . . . . . 10
81 8.2. Registration of CREATE-SPECIAL-USE IMAP Capability . . . . 10
82 8.3. Registration of SPECIAL-USE IMAP Capability . . . . . . . 10
83 8.4. Registration of SPECIAL-USE Selection Option . . . . . . . 10
84 8.5. Registration of SPECIAL-USE Return Option . . . . . . . . 11
85 8.6. Registration of SPECIAL-USE Metadata . . . . . . . . . . . 11
86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
87 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12
88 9.2. Informative References . . . . . . . . . . . . . . . . . . 12
114Leiba & Nicolson Standards Track [Page 2]
116RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
121 Some IMAP message stores include special-use mailboxes, such as those
122 used to hold draft messages or sent messages. Many mail clients
123 allow users to specify where draft or sent messages should be put,
124 but configuring them requires that the user know which mailboxes the
125 server has set aside for these purposes. This extension adds new
126 optional mailbox attributes that a server may include in IMAP LIST
127 command responses to identify special-use mailboxes to the client,
128 easing configuration.
130 In addition, this extension adds an optional parameter on the IMAP
131 CREATE command, allowing a client to assign a special use to a
132 mailbox when it is created. Servers may choose to support this part
133 of the extension, but are not required to.
1351.1. Conventions Used in This Document
137 In examples, "C:" indicates lines sent by a client that is connected
138 to a server. "S:" indicates lines sent by the server to the client.
140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
142 document are to be interpreted as described in RFC 2119 [RFC2119].
147 the following attributes in responses to the non-extended IMAP LIST
148 command. The new attributes are included along with existing
149 attributes, such as "\Marked" and "\Noselect". A given mailbox may
150 have none, one, or more than one of these attributes. In some cases,
151 a special use is advice to a client about what to put in that
152 mailbox. In other cases, it's advice to a client about what to
153 expect to find there. There is no capability string related to the
154 support of special-use attributes on the non-extended LIST command.
156 For the extended list command [RFC5258], this extension adds a new
157 capability string, a new selection option, and a new return option,
158 all called "SPECIAL-USE". Supporting implementations MUST include
159 the "SPECIAL-USE" capability string in response to an IMAP CAPABILITY
160 command. If the client specifies the "SPECIAL-USE" selection option,
161 the LIST command MUST return only those mailboxes that have a
162 special-use attribute set. If the client specifies the "SPECIAL-USE"
163 return option, the LIST command MUST return the new special-use
164 attributes on those mailboxes that have them set. The "SPECIAL-USE"
170Leiba & Nicolson Standards Track [Page 3]
172RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
175 return option is implied by the "SPECIAL-USE" selection option. The
176 extended LIST command MAY return SPECIAL-USE attributes even if the
177 client does not specify the return option.
179 The new attributes defined here are as follows:
182 This mailbox presents all messages in the user's message store.
183 Implementations MAY omit some messages, such as, perhaps, those
184 in \Trash and \Junk. When this special use is supported, it is
185 almost certain to represent a virtual mailbox.
188 This mailbox is used to archive messages. The meaning of an
189 "archival" mailbox is server-dependent; typically, it will be
190 used to get messages out of the inbox, or otherwise keep them
191 out of the user's way, while still making them accessible.
194 This mailbox is used to hold draft messages -- typically,
195 messages that are being composed but have not yet been sent. In
196 some server implementations, this might be a virtual mailbox,
197 containing messages from other mailboxes that are marked with
198 the "\Draft" message flag. Alternatively, this might just be
199 advice that a client put drafts here.
202 This mailbox presents all messages marked in some way as
203 "important". When this special use is supported, it is likely
204 to represent a virtual mailbox collecting messages (from other
205 mailboxes) that are marked with the "\Flagged" message flag.
208 This mailbox is where messages deemed to be junk mail are held.
209 Some server implementations might put messages here
210 automatically. Alternatively, this might just be advice to a
211 client-side spam filter.
214 This mailbox is used to hold copies of messages that have been
215 sent. Some server implementations might put messages here
216 automatically. Alternatively, this might just be advice that a
217 client save sent messages here.
220 This mailbox is used to hold messages that have been deleted or
221 marked for deletion. In some server implementations, this might
222 be a virtual mailbox, containing messages from other mailboxes
226Leiba & Nicolson Standards Track [Page 4]
228RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
231 that are marked with the "\Deleted" message flag.
232 Alternatively, this might just be advice that a client that
233 chooses not to use the IMAP "\Deleted" model should use this as
234 its trash location. In server implementations that strictly
235 expect the IMAP "\Deleted" model, this special use is likely not
238 All of the above attributes are OPTIONAL, and any given server or
239 message store may support any combination of the attributes, or none
240 at all. In most cases, there will likely be at most one mailbox with
241 a given attribute for a given user, but in some server or message
242 store implementations it might be possible for multiple mailboxes to
243 have the same special-use attribute.
245 Special-use attributes are likely to be user-specific. User Adam
246 might share his \Sent mailbox with user Barb, but that mailbox is
247 unlikely to also serve as Barb's \Sent mailbox. It's certainly
248 possible for Adam and Barb to each set the \Sent use on the same
249 mailbox, but that would be done by specific action (see the sections
2523. Extension to IMAP CREATE Command to Set Special-Use Attributes
254 As an OPTIONAL feature, a server MAY allow clients to designate a
255 mailbox, at creation, as having one or more special uses. This
256 extension defines the "USE" parameter to the IMAP CREATE command for
257 that purpose (using the syntax defined in RFC 4466 section 2.2
258 [RFC4466]). The new OPTIONAL "USE" parameter is followed by a
259 parenthesized list of zero or more special-use attributes, as defined
262 In some server implementations, some special uses may imply automatic
263 action by the server. For example, creation of a "\Junk" mailbox
264 might cause the server to start placing messages that have been
265 evaluated as spam into the mailbox.
267 In some server implementations, some special uses may result in a
268 mailbox with unusual characteristics or side effects. For example,
269 creation of an "\All" mailbox might cause the server to create a
270 virtual mailbox, rather than a standard one, and that mailbox might
271 behave in unexpected ways (COPY into it might fail, for example).
273 Servers MAY allow the creation of a special-use mailbox even if one
274 so designated already exists. This might have the effect of moving
275 the special use from the old mailbox to the new one, or might create
276 multiple mailboxes with the same special use. Alternatively, servers
277 MAY refuse the creation, considering the designation to be a
282Leiba & Nicolson Standards Track [Page 5]
284RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
287 If the server cannot create a mailbox with the designated special use
288 defined, for whatever reason, it MUST NOT create the mailbox, and
289 MUST respond to the CREATE command with a tagged NO response. If the
290 reason for the failure is related to the special-use attribute (the
291 specified special use is not supported or cannot be assigned to the
292 specified mailbox), the server SHOULD include the new "USEATTR"
293 response code in the tagged response (see Section 5.3 for an
297 "CREATE-SPECIAL-USE" capability string. Clients MUST NOT use the
298 "USE" parameter unless the server advertises the capability. Note
299 that this capability string is different from the "SPECIAL-USE"
300 string defined above, and a server that supports both functions MUST
301 advertise both capability strings.
3034. IMAP METADATA Entry for Special-Use Attributes
305 If a server supports this extension and the METADATA extension
306 [RFC5464], it SHOULD tie the special-use attributes for a mailbox to
307 its metadata entry "/private/specialuse". The value of /private/
308 specialuse is either NIL (if there are no special-use attributes for
309 that mailbox) or a space-separated list of special-use attributes,
310 presented the same way they would be presented in the LIST command
313 Such a server MAY allow the setting of special-use attributes through
314 the METADATA mechanisms, thereby allowing clients to change the
315 special uses of existing mailboxes. These changes might have side
316 effects, as the server automatically adjusts the special uses
317 accordingly, just as it might do with CREATE USE, above. See
318 Section 5.4 for an example.
320 A server that supports this MUST check the validity of changes to the
321 special-use attributes that are done through the metadata in the same
322 way that it checks validity for the CREATE command and for any
323 internal mechanisms for setting special uses on mailboxes. It MUST
324 NOT just blindly accept setting of these metadata by clients, which
325 might result in the setting of special uses that the implementation
326 does not support, multiple mailboxes with the same special use, or
327 other situations that the implementation considers invalid.
338Leiba & Nicolson Standards Track [Page 6]
340RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
3455.1. Example of an IMAP LIST Command
348 this extension. Note that not all of the attributes are used. This
349 server also supports the Child Mailbox extension [RFC3348].
352 S: * LIST (\Marked \HasNoChildren) "/" Inbox
353 S: * LIST (\HasNoChildren) "/" ToDo
354 S: * LIST (\HasChildren) "/" Projects
355 S: * LIST (\Sent \HasNoChildren) "/" SentMail
356 S: * LIST (\Marked \Drafts \HasNoChildren) "/" MyDrafts
357 S: * LIST (\Trash \HasNoChildren) "/" Trash
3605.2. Example of an Extended IMAP LIST Command
362 This example shows an IMAP LIST response from a server that supports
363 this extension. The client uses the extended IMAP LIST command.
366 S: * CAPABILITY IMAP4rev1 SPECIAL-USE
369 C: t2 LIST "" "%" RETURN (SPECIAL-USE)
370 S: * LIST (\Marked) "/" Inbox
371 S: * LIST () "/" ToDo
372 S: * LIST () "/" Projects
373 S: * LIST (\Sent) "/" SentMail
374 S: * LIST (\Marked \Drafts) "/" MyDrafts
375 S: * LIST (\Trash) "/" Trash
378 Here, the client also includes the "SPECIAL-USE" selection option for
379 the same list. The "SPECIAL-USE" return option could also have been
380 specified, but it is unnecessary, as it is implied by the selection
381 option. Note that in this case, mailboxes that do not have a
382 special-use attribute are not listed. Also note that we've used the
383 wildcard "*", rather than "%", to make sure we see all special-use
384 mailboxes, even ones that might not be at the namespace's root.
386 C: t3 LIST (SPECIAL-USE) "" "*"
387 S: * LIST (\Sent) "/" SentMail
388 S: * LIST (\Marked \Drafts) "/" MyDrafts
389 S: * LIST (\Trash) "/" Trash
394Leiba & Nicolson Standards Track [Page 7]
396RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
3995.3. Example of an IMAP CREATE Command
401 This example shows an IMAP CREATE command that might be used to
402 create a mailbox designated to hold draft and sent messages. It also
403 attempts to create a mailbox that will contain all the user's
404 messages, but the server does not support that special use for this
405 user's message store.
408 S: * CAPABILITY IMAP4rev1 CREATE-SPECIAL-USE
412 S: t2 OK MySpecial created
414 C: t3 CREATE Everything (USE (\All))
415 S: t3 NO [USEATTR] \All not supported
4175.4. Example of Using IMAP METADATA to Manipulate Special-Use
420 This example shows how IMAP METADATA can be used to manipulate
421 special-use attributes, if the operation is supported on the server.
424 C: t1 LIST "" "%" RETURN (SPECIAL-USE)
425 S: * LIST (\Sent) "/" SentMail
426 S: * LIST (\Drafts) "/" MyDrafts
427 S: * LIST () "/" SavedDrafts
428 S: * LIST (\Trash) "/" Trash
431 ==> Demonstrate the connection:
432 C: t2 GETMETADATA "MyDrafts" /private/specialuse
433 S: * METADATA "MyDrafts" (/private/specialuse "\\Drafts")
436 ==> Set new use for SavedDrafts; MyDrafts changes automatically:
437 C: t3 SETMETADATA "SavedDrafts" (/private/specialuse "\\Drafts")
438 S: * METADATA "MyDrafts" (/private/specialuse NIL)
439 S: t3 OK SETMETADATA complete
441 ==> Remove special use for SentMail:
442 C: t4 SETMETADATA "SentMail" (/private/specialuse NIL)
443 S: t4 OK SETMETADATA complete
450Leiba & Nicolson Standards Track [Page 8]
452RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
455 ==> Check the results:
456 C: t5 LIST "" "%" RETURN (SPECIAL-USE)
457 S: * LIST () "/" SentMail
458 S: * LIST () "/" MyDrafts
459 S: * LIST (\Drafts) "/" SavedDrafts
460 S: * LIST (\Trash) "/" Trash
465 The following syntax specification uses the augmented Backus-Naur
466 Form (BNF) as described in [RFC5234].
469 ; Extends "create-param" from RFC 4466 [RFC4466]
471 mbx-list-oflag =/ use-attr
472 ; Extends "mbx-list-oflag" from IMAP base [RFC3501]
474 list-select-independent-opt =/ "SPECIAL-USE"
475 ; Extends "list-select-independent-opt" from
476 ; LIST-extended [RFC5258]
479 ; Extends "return-option" from
480 ; LIST-extended [RFC5258]
482 resp-text-code =/ "USEATTR"
483 ; Extends "resp-text-code" from
486 use-attr = "\All" / "\Archive" / "\Drafts" / "\Flagged" /
487 "\Junk" / "\Sent" / "\Trash" / use-attr-ext
489 use-attr-ext = "\" atom
490 ; Reserved for future extensions. Clients
491 ; MUST ignore list attributes they do not understand
492 ; Server implementations MUST NOT generate
493 ; extension attributes except as defined by
494 ; future Standards-Track revisions of or
495 ; extensions to this specification.
4977. Security Considerations
500 Conveying special-use information to a client exposes a small bit of
501 extra information that could be of value to an attacker. Knowing,
502 for example, that a particular mailbox (\All) contains pointers to
506Leiba & Nicolson Standards Track [Page 9]
508RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
511 every message the user has might be of particular value. If the IMAP
512 channel is not protected from passive eavesdropping, this could be an
515 CREATE command "USE" parameter and metadata extension: In some server
516 implementations, some special uses may imply automatic action by the
517 server. For example, creation of a "\Junk" mailbox might cause the
518 server to start placing messages that have been evaluated as spam
519 into the mailbox. Implementors SHOULD consider the consequences of
520 allowing a user (or client program) to designate the target of such
523 Example: If a user is allowed to give the "\Junk" attribute to a
524 shared mailbox, legitimate mail that's misclassified as junk (false
525 positives) will be put into that shared mailbox, exposing the user's
526 private mail to others. The server might warn a user of that
527 possibility, or might refuse to allow the specification to be made on
528 a shared mailbox. (Note that this problem exists independent of this
529 specification, if the server allows a user to share a mailbox that's
530 already in use for such a function.)
5328. IANA Considerations
5348.1. Registration of USEATTR IMAP Response Code
536 This document defines a new IMAP response code, "USEATTR", which IANA
537 added to the IMAP Response Codes registry.
5398.2. Registration of CREATE-SPECIAL-USE IMAP Capability
541 This document defines a new IMAP capability, "CREATE-SPECIAL-USE",
542 which IANA added to the IMAP 4 Capabilities registry.
5448.3. Registration of SPECIAL-USE IMAP Capability
546 This document defines a new IMAP capability, "SPECIAL-USE", which
547 IANA added to the IMAP 4 Capabilities registry.
5498.4. Registration of SPECIAL-USE Selection Option
551 This document defines a new IMAP4 List Extended selection option,
552 "SPECIAL-USE", which IANA added to the IMAP4 List Extended registry,
556 Subject: Registration of LIST-EXTENDED selection option SPECIAL-USE
557 LIST-EXTENDED option name: SPECIAL-USE
558 LIST-EXTENDED option type: SELECTION
562Leiba & Nicolson Standards Track [Page 10]
564RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
567 Implied return option(s): SPECIAL-USE
568 LIST-EXTENDED option description: Limit the list to special-use
570 Published specification: RFC 6154
571 Security considerations: none
572 Intended usage: COMMON
573 Person and email address to contact for further information: Authors'
574 Addresses at the end of RFC 6154
575 Owner/Change controller: iesg@ietf.org
5778.5. Registration of SPECIAL-USE Return Option
579 This document defines a new IMAP4 List Extended return option,
580 "SPECIAL-USE", which IANA added to the IMAP4 List Extended registry,
584 Subject: Registration of LIST-EXTENDED return option SPECIAL-USE
585 LIST-EXTENDED option name: SPECIAL-USE
586 LIST-EXTENDED option type: RETURN
587 LIST-EXTENDED option description: Request special-use mailbox
589 Published specification: RFC 6154
590 Security considerations: none
591 Intended usage: COMMON
592 Person and email address to contact for further information: Authors'
593 Addresses at the end of RFC 6154
594 Owner/Change controller: iesg@ietf.org
5968.6. Registration of SPECIAL-USE Metadata
598 This document defines a new IMAP METADATA entry. IANA added the
599 following to the IMAP METADATA Mailbox Entry registry:
602 Subject: IMAP METADATA Entry Registration
604 Name: /private/specialuse
605 Description: Defines any special-use features of a mailbox. See the
606 reference specification for details of its use.
607 Content-type: text/plain; charset=us-ascii
609 Contact: MORG mailing list mailto:morg@ietf.org
618Leiba & Nicolson Standards Track [Page 11]
620RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
6259.1. Normative References
627 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
628 Requirement Levels", BCP 14, RFC 2119, March 1997.
630 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
631 4rev1", RFC 3501, March 2003.
633 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
634 ABNF", RFC 4466, April 2006.
636 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
637 Specifications: ABNF", STD 68, RFC 5234, January 2008.
639 [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access
640 Protocol version 4 - LIST Command Extensions", RFC 5258,
643 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
6469.2. Informative References
648 [RFC3348] Gahrns, M. and R. Cheng, "The Internet Message Action
649 Protocol (IMAP4) Child Mailbox Extension", RFC 3348,
657 Phone: +1 646 827 0648
658 EMail: barryleiba@computer.org
659 URI: http://internetmessagingtechnology.org/
665 EMail: nicolson@google.com
674Leiba & Nicolson Standards Track [Page 12]