IMAP LIST extension for special-use mailboxes
draft-ietf-morg-list-specialuse-03

Abstract

Some IMAP message stores include special-use mailboxes, such as those used to hold draft messages or sent messages. Many mail clients allow users to specify where draft or sent messages should be put, but configuring them requires that the user know which mailboxes the server has set aside for these purposes. This extension adds new mailbox flags that a server MAY include in IMAP LIST command responses to identify special-use mailboxes to the client, easing configuration.

Note

A revised version of this draft document will be submitted to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested, and should be sent to morg@ietf.org.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on May 12, 2011.

Copyright Notice

Copyright (c) 2010 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Introduction
1.1.  Conventions used in this document

2.  New mailbox flags identifying special-use mailboxes

3.  Extension to IMAP CREATE command to set special-use flags

4.  IMAP METADATA entry for special-use flags

5.  Examples
5.1.  Example of an IMAP LIST command
5.2.  Example of an extended IMAP LIST command
5.3.  Example of an IMAP CREATE command
5.4.  Example of using IMAP METADATA to manipulate special-use flags

6.  Formal Syntax

7.  Security Considerations

8.  IANA Considerations
8.1.  Registration of USEFLAG IMAP response code
8.2.  Registration of CREATE-SPECIAL-USE IMAP capability
8.3.  Registration of SPECIAL-USE IMAP capability
8.4.  Registration of SPECIAL-USE selection option
8.5.  Registration of SPECIAL-USE return option
8.6.  Registration of SPECIAL-USE metadata

9.  References
9.1.  Normative References
9.2.  Informative References

§  Authors' Addresses

1.  Introduction

Some IMAP message stores include special-use mailboxes, such as those used to hold draft messages or sent messages. Many mail clients allow users to specify where draft or sent messages should be put, but configuring them requires that the user know which mailboxes the server has set aside for these purposes. This extension adds new mailbox flags that a server MAY include in IMAP LIST command responses to identify special-use mailboxes to the client, easing configuration.

In addition, this extension adds an OPTIONAL parameter on the IMAP CREATE command, allowing a client to assign a special use to a mailbox when it is created. Servers MAY choose to support this part of the extension, but are not required to.

1.1.  Conventions used in this document

In examples, "C:" indicates lines sent by a client that is connected to a server. "S:" indicates lines sent by the server 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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

2.  New mailbox flags identifying special-use mailboxes

An IMAP server that supports this extension MAY include any or all of the following flags in responses to the non-extended IMAP LIST command. The new flags are included along with existing flags, such as "\Marked" and "\Noselect". A given mailbox may have none, one, or more than one of these flags. In some cases, a special use is advice to a client about what to put in that mailbox. In other cases, it's advice to a client about what to expect to find there. There is no capability string related to the support of special-use flags on the non-extended LIST command.

For the extended list command [RFC5258] (Leiba, B. and A. Melnikov, “Internet Message Access Protocol version 4 - LIST Command Extensions,” June 2008.), 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 flag set. If the client specifies the "SPECIAL-USE" return option, the LIST command MUST return the new special-use flags 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 flags even if the client does not specify the return option.

The new flags defined here are as follows:

\Drafts

This mailbox is used to hold draft messages -- typically, messages that are being composed but have not yet been sent. In some server implementations, this might be a virtual mailbox, containing messages from other mailboxes that are marked with the "\Draft" message flag. Alternatively, this might just be advice that a client put drafts here.

\Flagged

This mailbox presents all messages marked in some way as "important". When this special use is supported, it is likely to represent a virtual mailbox collecting messages (from other mailboxes) that are marked with the "\Flagged" message flag.

\Junk

This mailbox is where messages deemed to be junk mail are held. Some server implementations might put messages here automatically. Alternatively, this might just be advice to a client-side spam filter.

\Sent

This mailbox is used to hold copies of messages that have been sent. Some server implementations might put messages here automatically. Alternatively, this might just be advice that a client save sent messages here.

\Trash

This mailbox is used to hold messages that have been deleted, or marked for deletion. In some server implementations, this might be a virtual mailbox, containing messages from other mailboxes that are marked with the "\Deleted" message flag. Alternatively, this might just be advice that a client that chooses not to use the IMAP "\Deleted" model should use this as its trash location. In server implementations that strictly expect the IMAP "\Deleted" model, this special use is likely not to be supported.

\All

This mailbox presents all messages in the user's message store. Implementations MAY omit some messages, such as, perhaps, those in \Trash and \Junk. When this special use is supported, it is almost certain to represent a virtual mailbox.

\Archive

This mailbox is used to archive messages. The meaning of an "archival" mailbox is server-dependent; typically, it will be used to get messages out of the inbox, or otherwise keep them out of the user's way, while still making them accessible.

All of the above flags are OPTIONAL, and any given server or message store may support any combination of the flags, or none at all. In some server or message store implementations it might be possible for multiple mailboxes to have the same special-use flag.

3.  Extension to IMAP CREATE command to set special-use flags

As an OPTIONAL feature, a server MAY allow clients to designate a mailbox, at creation, as having one or more special uses. This extension defines the "USE" parameter to the IMAP CREATE command for that purpose (using the syntax defined in RFC 4466 section 2.2 [RFC4466] (Melnikov, A. and C. Daboo, “Collected Extensions to IMAP4 ABNF,” April 2006.)). The new OPTIONAL "USE" parameter is followed by a parenthesized list of zero or more special-use flags, as defined above.

In some server implementations, some special uses may imply automatic action by the server. For example, creation of a "\Junk" mailbox might cause the server to start placing messages that have been evaluated as spam into the mailbox.

In some server implementations, some special uses may result in a mailbox with unusual characteristics or side effects. For example, creation of an "\All" mailbox might cause the server to create a virtual mailbox, rather than a standard one, and that mailbox might behave in unexpected ways (COPY into it might fail, for example).

Servers MAY allow the creation of a special-use mailbox even if one so designated already exists, having the effect of moving the special use from the old mailbox to the new one. Alternatively, servers MAY refuse the creation, considering the designation to be a conflict.

If the server can not create a mailbox with the designated special use defined, for whatever reason, it MUST NOT create the mailbox, and MUST respond to the CREATE command with a tagged NO response. If the reason for the failure is related to the special-use flag (the specified special use is not supported or cannot be assigned to the specified mailbox), the server SHOULD include the new "USEFLAG" response code in the tagged response (see Section 5.3 (Example of an IMAP CREATE command) 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 the capability. Note that this capability string is different from the SPECIAL-USE string defined above, and a server that supports both functions MUST advertise both capability strings.

4.  IMAP METADATA entry for special-use flags

If a server supports this extension and the METADATA extension [RFC5464] (Daboo, C., “The IMAP METADATA Extension,” February 2009.), it SHOULD tie the special-use flags for a mailbox to its metadata entry "/shared/specialuse". The value of /shared/specialuse is either NIL (if there are no special-use flags for that mailbox) or a space-separated list of special-use flags, presented the same way they would be presented in the LIST command response.

Such a server MAY allow the setting of special-use flags through the METADATA mechanisms, thereby allowing clients to change the special uses of existing mailboxes. These changes might have side effects, as the server automatically adjusts the special uses accordingly, just as it might do with CREATE USE, above. See Section 5.4 (Example of using IMAP METADATA to manipulate special-use flags) for an example.

A server that supports this MUST check the validity of changes to the special-use flags that are done through the metadata. It MUST NOT allow a client to set invalid or unsupported flags, nor to create conflicting or otherwise invalid situations.

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 flags are used. This server also supports the Child Mailbox extension [RFC3348] (Gahrns, M. and R. Cheng, “The Internet Message Action Protocol (IMAP4) Child Mailbox Extension,” July 2002.).

  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 done

5.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 done

Here, 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 is unnecessary, as it is implied by the selection option. Note that in this case, mailboxes that do not have a special-use flag are not listed.

  C: t3 LIST (SPECIAL-USE) "" "%"
  S: * LIST (\Sent) "/" SentMail
  S: * LIST (\Marked \Drafts) "/" MyDrafts
  S: * LIST (\Trash) "/" Trash
  S: t3 OK done

5.3.  Example of an IMAP CREATE command

This example shows an IMAP CREATE command that might be used to create a mailbox designated to hold draft and sent messages. It also attempts to create a mailbox that will contain all the user's messages, but the server does not 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 [USEFLAG] \All not supported

5.4.  Example of using IMAP METADATA to manipulate special-use flags

This example shows how IMAP METADATA can be used to manipulate special-use flags, 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" /shared/specialuse
  S: * METADATA "MyDrafts" (/shared/specialuse "\Drafts")
  S: t2 OK done

  ==> Set new use for SavedDrafts; MyDrafts changes automatically:
  C: t3 SETMETADATA "SavedDrafts" (/shared/specialuse "\Drafts")
  S: * METADATA "MyDrafts" (/shared/specialuse NIL)
  S: t3 OK SETMETADATA complete

  ==> Remove special use for SentMail:
  C: t4 SETMETADATA "SentMail" (/shared/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 done

6.  Formal Syntax

The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in [RFC5234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.).

create-param =/

"USE" SP "(" [use-flag *(SP use-flag)] ")" ; Extends "create-param" from RFC 4466 [RFC4466] (Melnikov, A. and C. Daboo, “Collected Extensions to IMAP4 ABNF,” April 2006.)

mbx-list-oflag =/

use-flag ; Extends "mbx-list-oflag" from IMAP base [RFC3501] (Crispin, M., “INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1,” March 2003.)

list-select-independent-opt =/

"SPECIAL-USE" ; Extends "list-select-independent-opt" from
; LIST-extended [RFC5258] (Leiba, B. and A. Melnikov, “Internet Message Access Protocol version 4 - LIST Command Extensions,” June 2008.)

return-option =/

"SPECIAL-USE" ; Extends "return-option" from
; LIST-extended [RFC5258] (Leiba, B. and A. Melnikov, “Internet Message Access Protocol version 4 - LIST Command Extensions,” June 2008.)

resp-text-code =/

"USEFLAG" ; Extends "resp-text-code" from
; IMAP [RFC5258] (Leiba, B. and A. Melnikov, “Internet Message Access Protocol version 4 - LIST Command Extensions,” June 2008.)

use-flag =

"\All" / "\Archive" / "\Drafts" / "\Flagged" / "\Junk" / "\Sent" / "\Trash" / use-flag-ext

use-flag-ext =

"\" atom ; Reserved for future extensions. Clients
; MUST ignore list flags they do not understand
; Server implementations MUST NOT generate
; extension flags except as defined by
; future standards-track revisions of or
; extensions to this specification.

7.  Security Considerations

LIST response: There are no security issues with conveying special-use information to a client.

CREATE command "USE" parameter: In some server implementations, some special uses may imply automatic action by the server. For example, creation of a "\Junk" mailbox might cause the server to start placing messages that have been evaluated as spam into the mailbox. Server implementors SHOULD consider the consequences of allowing a user (or client program) to designate the target of such automatic action.

8.  IANA Considerations

8.1.  Registration of USEFLAG IMAP response code

This document defines a new IMAP response code. IANA is asked to add "USEFLAG" to the IMAP Response Codes registry.

8.2.  Registration of CREATE-SPECIAL-USE IMAP capability

This document defines a new IMAP capability. IANA is asked to add "CREATE-SPECIAL-USE" to the IMAP 4 Capabilities registry.

8.3.  Registration of SPECIAL-USE IMAP capability

This document defines a new IMAP capability. IANA is asked to add "SPECIAL-USE" to the IMAP 4 Capabilities registry.

8.4.  Registration of SPECIAL-USE selection option

This document defines a new IMAP4 List Extended selection option. IANA is asked to add "SPECIAL-USE" 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: [[this RFC]]
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors' Addresses at the end of [[this RFC]]
Owner/Change controller: iesg@ietf.org

8.5.  Registration of SPECIAL-USE return option

This document defines a new IMAP4 List Extended return option. IANA is asked to add "SPECIAL-USE" 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: [[this RFC]]
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors' Addresses at the end of [[this RFC]]
Owner/Change controller: iesg@ietf.org

8.6.  Registration of SPECIAL-USE metadata

This document defines a new IMAP METADATA entry. IANA is asked to add the following to the IMAP METADATA Mailbox Entry registry:

To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Mailbox
Name: /shared/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: [[this RFC]]
Contact: MORG mailing list mailto:morg@ietf.org

9.  References

9.1. Normative References

9.2. Informative References

Authors' Addresses