RFC 6154
IMAP LIST Extension for Special-Use Mailboxes
RFC 6154: IMAP LIST Extension for Special-Use Mailboxes 💌
Request for Comments 6154 🎀 — the IETF (Internet Engineering Task Force) doc, published March 2011.
Authors: B. Leiba (Huawei Technologies) and J. Nicolson (Google) 💅 Category: Standards Track 👑 (an Internet Standards Track doc, so it's official) ISSN: 2070-1721 Obsoletes / Updates: the title block doesn't list anything it obsoletes or updates 🫶
Abstract ✨
okay so some IMAP message stores have special-use mailboxes 📬, like the ones that hold drafts or sent messages. Lots of mail clients let you pick where drafts and sent messages go 💖, but setting that up means you have to already know which mailboxes the server reserved for those jobs 🙈. This extension adds new optional mailbox attributes that a server may include in IMAP LIST command responses, so the client can spot the special-use mailboxes itself and config gets so much easier 🧚
Status of This Memo 🌸
This is an Internet Standards Track document 👑.
This doc is a product of the IETF. It represents the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 5741 📚.
For the current status of this document, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6154 🔗.
Copyright Notice 🌈
Copyright (c) 2011 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 (http://trustee.ietf.org/license-info) as they stand on the publication date. Please read these carefully 🙈, because they spell out your rights and restrictions for this doc. Code components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License ⚖️.
Table of Contents 🧾
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions Used in This Document . . . . . . . . . . . . 3
2. New Mailbox Attributes Identifying Special-Use Mailboxes . . . 3
3. Extension to IMAP CREATE Command to Set Special-Use
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. IMAP METADATA Entry for Special-Use Attributes . . . . . . . . 6
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Example of an IMAP LIST Command . . . . . . . . . . . . . 7
5.2. Example of an Extended IMAP LIST Command . . . . . . . . . 7
5.3. Example of an IMAP CREATE Command . . . . . . . . . . . . 8
5.4. Example of Using IMAP METADATA to Manipulate
Special-Use Attributes . . . . . . . . . . . . . . . . . . 8
6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8.1. Registration of USEATTR IMAP Response Code . . . . . . . . 10
8.2. Registration of CREATE-SPECIAL-USE IMAP Capability . . . . 10
8.3. Registration of SPECIAL-USE IMAP Capability . . . . . . . 10
8.4. Registration of SPECIAL-USE Selection Option . . . . . . . 10
8.5. Registration of SPECIAL-USE Return Option . . . . . . . . 11
8.6. Registration of SPECIAL-USE Metadata . . . . . . . . . . . 11
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References . . . . . . . . . . . . . . . . . . . 12
9.2. Informative References . . . . . . . . . . . . . . . . . . 121. Introduction ✨
okay so, some IMAP message stores have special-use mailboxes 📬, like the ones used to hold draft messages or sent messages. Lots of mail clients let users choose where drafts and sent messages end up 💅, but setting that up means the user has to already know which mailboxes the server set aside for those jobs 🙈. This extension adds new optional mailbox attributes that a server may include in IMAP LIST command responses to flag special-use mailboxes for the client, so config gets easier 🫶.
the extension also adds an optional parameter to the IMAP CREATE command 🌸, so a client can give a mailbox a special use right when it's created. Servers may choose to support this part of the extension, but they aren't required to 🦋.
1.1. Conventions Used in This Document 📖
in the examples, "C:" marks lines sent by a client that's connected to a server, and "S:" marks lines the server sends back to the client 💬.
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 RFC 2119 [RFC2119] 🔥.
2. New Mailbox Attributes Identifying Special-Use Mailboxes 🦋
An IMAP server that supports this extension MAY include any or all of the following attributes in responses to the non-extended IMAP LIST command 🧚. The new attributes show up alongside the existing ones, like "\Marked" and "\Noselect" ✨. A given mailbox may have none, one, or more than one of these attributes. Sometimes a special use is advice to the client about what to put in that mailbox 💌, and other times it's advice about what to expect to find there 🔍. There's no capability string for special-use attributes on the non-extended LIST command, btw 🙈.
For the extended list command [RFC5258], this extension adds a new capability string, a new selection option, and a new return option, all called "SPECIAL-USE" 👑. Supporting implementations MUST include the "SPECIAL-USE" capability string in response to an IMAP CAPABILITY command 💅. If the client specifies the "SPECIAL-USE" selection option, the LIST command MUST return only those mailboxes that have a special-use attribute set 🎀. If the client specifies the "SPECIAL-USE" return option, the LIST command MUST return the new special-use attributes on those mailboxes that have them set 💖. The "SPECIAL-USE" return option is implied by the "SPECIAL-USE" selection option. The extended LIST command MAY return SPECIAL-USE attributes even if the client doesn't specify the return option 🌈.
The new attributes defined here are:
\All: This mailbox presents all messages in the user's message store 📬. Implementations MAY omit some messages, such as, perhaps, those in\Trashand\Junk. When this special use is supported, it is almost certain to be a virtual mailbox 🧚.\Archive: This mailbox is used to archive messages 🗂️. What an "archival" mailbox means depends on the server. Usually it's where messages go to get out of the inbox, or otherwise stay out of the user's way while still being accessible 🦋.\Drafts: This mailbox holds draft messages, usually ones still being composed and not yet sent ✍️. On some servers it's a virtual mailbox with messages from other mailboxes that carry the\Draftmessage flag. Otherwise it might just be advice that a client should put drafts here 💅.\Flagged: This mailbox presents all messages marked in some way as "important" ⭐. When this special use is supported, it's likely a virtual mailbox that collects messages (from other mailboxes) carrying the\Flaggedmessage flag 🔥.\Junk: This mailbox is where messages deemed junk mail end up 🗑️. Some servers might file messages here automatically. Otherwise it might just be advice to a client-side spam filter 🙈.\Sent: This mailbox holds copies of messages that have been sent 📤. Some servers might put messages here automatically. Otherwise it might just be advice that a client save sent messages here 💌.\Trash: This mailbox holds messages that have been deleted or marked for deletion 🗑️. On some servers it's a virtual mailbox with messages from other mailboxes that carry the\Deletedmessage flag. Otherwise it might just be advice that a client which doesn't use the IMAP\Deletedmodel should use this as its trash spot 🌸. On servers that strictly expect the IMAP\Deletedmodel, this special use probably won't be supported 💀.
All of the above attributes are OPTIONAL 🌈, and any given server or message store may support any combination of them, or none at all. In most cases there will likely be at most one mailbox with a given attribute for a given user, but on some server or message store implementations it might be possible for multiple mailboxes to share the same special-use attribute 🧩.
Special-use attributes are likely to be user-specific 👑. Say user Adam shares his \Sent mailbox with user Barb. That mailbox is unlikely to also serve as Barb's \Sent mailbox 💅. It's totally possible for Adam and Barb to each set the \Sent use on the same mailbox, but that takes a specific action (see the sections below) ✨.
Part 1 of 3! 🎀 More parts coming, so stay tuned bestie 🫶
3. Extension to IMAP CREATE Command to Set Special-Use Attributes 🎀
Okay so, this part is OPTIONAL 💅 A server MAY let clients pick special uses for a mailbox right when it gets created. This extension adds a "USE" parameter to the IMAP CREATE command to make that happen (using the syntax from RFC 4466 section 2.2 [RFC4466]). The new OPTIONAL "USE" parameter is followed by a parenthesized list of zero or more special-use attributes, the same ones we went over above. 🦋
Some server implementations might do automatic stuff when a special use gets set. Like, making a "\Junk" mailbox could make the server start dumping messages it thinks are spam into it. 🙈
Some server implementations can also end up with mailboxes that act kinda weird or have side effects. For example, creating an "\All" mailbox might make the server build a virtual mailbox instead of a normal one, and that mailbox could act unexpectedly (COPY into it might fail, for example) 💀
Servers MAY allow the creation of a special-use mailbox even if one already exists with that designation. That could move the special use from the old mailbox over to the new one, or it could make multiple mailboxes with the same special use. Or, alternatively, servers MAY refuse it and treat it as a conflict. 🌸
If the server can't create a mailbox with the designated special use, for whatever reason, it MUST NOT create the mailbox, and it MUST respond to the CREATE command with a tagged NO response. 😭 If the problem is with the special-use attribute itself (the special use isn't supported, or it can't be assigned to that mailbox), the server SHOULD include the new "USEATTR" response code in the tagged response (see Section 5.3 for an example). ✨
An IMAP server that supports this OPTIONAL feature will advertise the "CREATE-SPECIAL-USE" capability string. Clients MUST NOT use the "USE" parameter unless the server advertises that capability.
Heads up, bestie! The "CREATE-SPECIAL-USE" string is different from the "SPECIAL-USE" string we talked about earlier. A server that supports both functions MUST advertise both capability strings. 🚨
4. IMAP METADATA Entry for Special-Use Attributes ✨
If a server supports this extension and the METADATA extension [RFC5464], it SHOULD tie a mailbox's special-use attributes to its metadata entry "/private/specialuse". The value of /private/specialuse is either NIL (if that mailbox has no special-use attributes) or a space-separated list of special-use attributes, shown the same way they'd appear in a LIST command response. 🧚
Such a server MAY let clients set special-use attributes through the METADATA mechanisms, so clients can change the special uses of mailboxes that already exist. These changes might have side effects, since the server automatically adjusts special uses accordingly, just like it might do with CREATE USE above. Check out Section 5.4 for an example. 💜
A server that supports this MUST check the validity of changes to special-use attributes made through metadata, in the same way it checks validity for the CREATE command and for any internal mechanisms that set special uses on mailboxes. It MUST NOT just blindly accept those metadata settings from clients, because that could result in special uses the implementation doesn't support, multiple mailboxes with the same special use, or other situations the implementation considers invalid. 🚫
5. Examples 🌈
5.1. Example of an IMAP LIST Command
This example shows an IMAP LIST response from a server that supports this extension. Note that not all of the attributes are used. This server also supports the Child Mailbox extension [RFC3348]. 🍓
C: t1 LIST "" "%"
S: * LIST (\Marked \HasNoChildren) "/" Inbox
S: * LIST (\HasNoChildren) "/" ToDo
S: * LIST (\HasChildren) "/" Projects
S: * LIST (\Sent \HasNoChildren) "/" SentMail
S: * LIST (\Marked \Drafts \HasNoChildren) "/" MyDrafts
S: * LIST (\Trash \HasNoChildren) "/" Trash
S: t1 OK done5.2. Example of an Extended IMAP LIST Command
This example shows an IMAP LIST response from a server that supports this extension. The client uses the extended IMAP LIST command. 💅
C: t1 CAPABILITY
S: * CAPABILITY IMAP4rev1 SPECIAL-USE
S: t1 OK done
C: t2 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST (\Marked) "/" Inbox
S: * LIST () "/" ToDo
S: * LIST () "/" Projects
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Marked \Drafts) "/" MyDrafts
S: * LIST (\Trash) "/" Trash
S: t2 OK doneHere, the client also includes the "SPECIAL-USE" selection option for the same list. The "SPECIAL-USE" return option could also have been specified, but it's unnecessary, since it's implied by the selection option. Note that in this case, mailboxes without a special-use attribute aren't listed. Also, we've used the wildcard "*" instead of "%" so we see all special-use mailboxes, even ones that might not be at the namespace's root. 👑
C: t3 LIST (SPECIAL-USE) "" "*"
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Marked \Drafts) "/" MyDrafts
S: * LIST (\Trash) "/" Trash
S: t3 OK done5.3. Example of an IMAP CREATE Command
This example shows an IMAP CREATE command that might be used to create a mailbox for draft and sent messages. It also tries to create a mailbox that would contain all the user's messages, but the server doesn't support that special use for this user's message store. 🙈
C: t1 CAPABILITY
S: * CAPABILITY IMAP4rev1 CREATE-SPECIAL-USE
S: t1 OK done
C: t2 CREATE MySpecial (USE (\Drafts \Sent))
S: t2 OK MySpecial created
C: t3 CREATE Everything (USE (\All))
S: t3 NO [USEATTR] \All not supported5.4. Example of Using IMAP METADATA to Manipulate Special-Use Attributes
This example shows how IMAP METADATA can be used to manipulate special-use attributes, if the operation is supported on the server. 🦋
==> Starting point:
C: t1 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Drafts) "/" MyDrafts
S: * LIST () "/" SavedDrafts
S: * LIST (\Trash) "/" Trash
S: t1 OK done
==> Demonstrate the connection:
C: t2 GETMETADATA "MyDrafts" /private/specialuse
S: * METADATA "MyDrafts" (/private/specialuse "\\Drafts")
S: t2 OK done
==> Set new use for SavedDrafts; MyDrafts changes automatically:
C: t3 SETMETADATA "SavedDrafts" (/private/specialuse "\\Drafts")
S: * METADATA "MyDrafts" (/private/specialuse NIL)
S: t3 OK SETMETADATA complete
==> Remove special use for SentMail:
C: t4 SETMETADATA "SentMail" (/private/specialuse NIL)
S: t4 OK SETMETADATA complete
==> Check the results:
C: t5 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST () "/" SentMail
S: * LIST () "/" MyDrafts
S: * LIST (\Drafts) "/" SavedDrafts
S: * LIST (\Trash) "/" Trash
S: t5 OK done6. Formal Syntax 🧩
The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in [RFC5234].
create-param =/ "USE" SP "(" [use-attr *(SP use-attr)] ")"
; Extends "create-param" from RFC 4466 [RFC4466]
mbx-list-oflag =/ use-attr
; Extends "mbx-list-oflag" from IMAP base [RFC3501]
list-select-independent-opt =/ "SPECIAL-USE"
; Extends "list-select-independent-opt" from
; LIST-extended [RFC5258]
return-option =/ "SPECIAL-USE"
; Extends "return-option" from
; LIST-extended [RFC5258]
resp-text-code =/ "USEATTR"
; Extends "resp-text-code" from
; IMAP [RFC3501]
use-attr = "\All" / "\Archive" / "\Drafts" / "\Flagged" /
"\Junk" / "\Sent" / "\Trash" / use-attr-ext
use-attr-ext = "\" atom
; Reserved for future extensions. Clients
; MUST ignore list attributes they do not understand
; Server implementations MUST NOT generate
; extension attributes except as defined by
; future Standards-Track revisions of or
; extensions to this specification.7. Security Considerations 🔐
This section is serious, bestie. Please read every part of it. 💀
LIST response: Conveying special-use information to a client exposes a small bit of extra information that could be valuable to an attacker. Knowing, for example, that a particular mailbox (\All) contains pointers to every message the user has might be especially valuable. If the IMAP channel isn't protected from passive eavesdropping, this could be an issue. 👀
CREATE command "USE" parameter and metadata extension: In some server implementations, some special uses may imply automatic action by the server. For example, creating a "\Junk" mailbox might cause the server to start placing messages that have been evaluated as spam into the mailbox. Implementors SHOULD consider the consequences of allowing a user (or client program) to designate the target of such automatic action.
Example: If a user is allowed to give the "\Junk" attribute to a shared mailbox, legitimate mail that's misclassified as junk (false positives) will be put into that shared mailbox, exposing the user's private mail to others. The server might warn the user about that possibility, or it might refuse to allow the specification to be made on a shared mailbox. (Note that this problem exists independent of this specification, if the server allows a user to share a mailbox that's already in use for such a function.) 😱
8. IANA Considerations 📝
8.1. Registration of USEATTR IMAP Response Code
This document defines a new IMAP response code, "USEATTR", which IANA added to the IMAP Response Codes registry. 🌸
8.2. Registration of CREATE-SPECIAL-USE IMAP Capability
This document defines a new IMAP capability, "CREATE-SPECIAL-USE", which IANA added to the IMAP 4 Capabilities registry. 🎀
8.3. Registration of SPECIAL-USE IMAP Capability
This document defines a new IMAP capability, "SPECIAL-USE", which IANA added to the IMAP 4 Capabilities registry. 🦋
8.4. Registration of SPECIAL-USE Selection Option
This document defines a new IMAP4 List Extended selection option, "SPECIAL-USE", which IANA added to the IMAP4 List Extended registry, as follows: 💖
To: iana@iana.org
Subject: Registration of LIST-EXTENDED selection option SPECIAL-USE
LIST-EXTENDED option name: SPECIAL-USE
LIST-EXTENDED option type: SELECTION
Implied return option(s): SPECIAL-USE
LIST-EXTENDED option description: Limit the list to special-use
mailboxes only
Published specification: RFC 6154
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors'
Addresses at the end of RFC 6154
Owner/Change controller: iesg@ietf.org8.5. Registration of SPECIAL-USE Return Option ✨
okay so this one is the registration for the SPECIAL-USE return option 🎀 IANA added it to the IMAP4 List Extended registry, and it's giving official paperwork energy 💅
This document defines a new IMAP4 List Extended return option, SPECIAL-USE, which IANA added to the IMAP4 List Extended registry, as follows:
To: iana@iana.org
Subject: Registration of LIST-EXTENDED return option SPECIAL-USE
LIST-EXTENDED option name: SPECIAL-USE
LIST-EXTENDED option type: RETURN
LIST-EXTENDED option description: Request special-use mailbox
information
Published specification: RFC 6154
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors'
Addresses at the end of RFC 6154
Owner/Change controller: iesg@ietf.org8.6. Registration of SPECIAL-USE Metadata 🧚
next up is the SPECIAL-USE metadata entry 🦋 this document defines a brand new IMAP METADATA entry, and IANA added it to the IMAP METADATA Mailbox Entry registry. ngl the little /private/specialuse name is so cute 🌸
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Mailbox
Name: /private/specialuse
Description: Defines any special-use features of a mailbox. See the
reference specification for details of its use.
Content-type: text/plain; charset=us-ascii
RFC Number: RFC 6154
Contact: MORG mailing list mailto:morg@ietf.org9. References 📚
9.1. Normative References 💜
these are the references the spec leans on hardcore, so no skipping 🙈
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access
Protocol version 4 - LIST Command Extensions", RFC 5258,
June 2008.
[RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
February 2009.9.2. Informative References 🌈
and these are the extra-helpful reads, good for background vibes 🍓
[RFC3348] Gahrns, M. and R. Cheng, "The Internet Message Action
Protocol (IMAP4) Child Mailbox Extension", RFC 3348,
July 2002.Authors' Addresses 🫶
the people who wrote this, with their contact info, all listed exactly as they appear ✨
Barry Leiba
Huawei Technologies
Phone: +1 646 827 0648
EMail: barryleiba@computer.org
URI: http://internetmessagingtechnology.org/
Jamie Nicolson
Google
EMail: nicolson@google.comand that's the whole spec, bestie!! 👑 the SPECIAL-USE return option, the metadata entry, the references, and the authors, all done 💖
📦 where this page comes from
- ietf: rfc6154 2011-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms