Message ORGanization Working Group                              B. Leiba
Internet-Draft                                       Huawei Technologies
Intended status: Standards Track                             J. Nicolson
Expires: June 4, 2011                                             Google
                                                        December 1, 2010


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

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 attributes 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 June 4, 2011.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the



Leiba & Nicolson          Expires June 4, 2011                  [Page 1]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


   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 . . . . . . . . . . . . . . . . . . . . . . . .  4
   1.1.  Conventions used in this document  . . . . . . . . . . . . .  4

   2.    New mailbox attributes identifying special-use mailboxes . .  4

   3.    Extension to IMAP CREATE command to set special-use
         attributes . . . . . . . . . . . . . . . . . . . . . . . . .  6

   4.    IMAP METADATA entry for special-use attributes . . . . . . .  7

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

   6.    Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . 10

   7.    Security Considerations  . . . . . . . . . . . . . . . . . . 10

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

   9.    References . . . . . . . . . . . . . . . . . . . . . . . . . 12
   9.1.  Normative References . . . . . . . . . . . . . . . . . . . . 12
   9.2.  Informative References . . . . . . . . . . . . . . . . . . . 13




Leiba & Nicolson          Expires June 4, 2011                  [Page 2]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


         Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 13


















































Leiba & Nicolson          Expires June 4, 2011                  [Page 3]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


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 attributes 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].


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 are included along with existing
   attributes, such as "\Marked" and "\Noselect".  A given mailbox may
   have none, one, or more than one of these attributes.  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 attributes on the non-extended LIST command.

   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



Leiba & Nicolson          Expires June 4, 2011                  [Page 4]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


   extended LIST command MAY return SPECIAL-USE attributes even if the
   client does not specify the return option.

   The new attributes 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.




Leiba & Nicolson          Expires June 4, 2011                  [Page 5]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


   \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 attributes are OPTIONAL, and any given server or
   message store may support any combination of the attributes, or none
   at all.  In some server or message store implementations it might be
   possible for multiple mailboxes to have the same special-use
   attribute.

   Special-use attributes are likely to be user-specific.  User Adam
   might share his \Sent mailbox with user Barb, but that mailbox is
   unlikely to also serve as Barb's \Sent mailbox.  It's certainly
   possible for Adam and Barb to each set the \Sent use on the same
   mailbox, but that would be done by specific action (see the sections
   below).


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

   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]).  The new OPTIONAL "USE" parameter is followed by a
   parenthesized list of zero or more special-use attributes, 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



Leiba & Nicolson          Expires June 4, 2011                  [Page 6]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


   MUST respond to the CREATE command with a tagged NO response.  If the
   reason for the failure is related to the special-use attribute (the
   specified special use is not supported or cannot be assigned to the
   specified 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 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 attributes

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

   Such a server MAY allow the setting of special-use attributes 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 for an example.

   A server that supports this MUST check the validity of changes to the
   special-use attributes that are done through the metadata.  It MUST
   NOT allow a client to set invalid or unsupported attributes, 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 attributes are used.  This
   server also supports the Child Mailbox extension [RFC3348].






Leiba & Nicolson          Expires June 4, 2011                  [Page 7]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


     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 attribute are not listed.  Also note that we've used the
   wildcard "*", rather than "%", to make sure 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 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.



Leiba & Nicolson          Expires June 4, 2011                  [Page 8]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


     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 supported

5.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" /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






Leiba & Nicolson          Expires June 4, 2011                  [Page 9]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


6.  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

   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.
   Implementors SHOULD consider the consequences of allowing a user (or
   client program) to designate the target of such automatic action.





Leiba & Nicolson          Expires June 4, 2011                 [Page 10]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


8.  IANA Considerations

8.1.  Registration of USEATTR IMAP response code

   This document defines a new IMAP response code.  IANA is asked to add
   "USEATTR" 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



Leiba & Nicolson          Expires June 4, 2011                 [Page 11]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


   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

   [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.





Leiba & Nicolson          Expires June 4, 2011                 [Page 12]


Internet-Draft      IMAP LIST: special-use mailboxes       December 2010


9.2.  Informative References

   [RFC3348]  Gahrns, M. and R. Cheng, "The Internet Message Action
              Protocol (IMAP4) Child Mailbox Extension", RFC 3348,
              July 2002.


Authors' Addresses

   Barry Leiba
   Huawei Technologies

   Phone: +1 646 827 0648
   Email: barryleiba@computer.org
   URI:   http://internetmessagingtechnology.org/


   Jamie Nicolson
   Google

   Email: nicolson@google.com






























Leiba & Nicolson          Expires June 4, 2011                 [Page 13]