7Network Working Group M. Gahrns
8Request for Comments: 2342 Microsoft
9Category: Standards Track C. Newman
18 This document specifies an Internet standards track protocol for the
19 Internet community, and requests discussion and suggestions for
20 improvements. Please refer to the current edition of the "Internet
21 Official Protocol Standards" (STD 1) for the standardization state
22 and status of this protocol. Distribution of this memo is unlimited.
26 Copyright (C) The Internet Society (1998). All Rights Reserved.
30 IMAP4 [RFC-2060] does not define a default server namespace. As a
31 result, two common namespace models have evolved:
33 The "Personal Mailbox" model, in which the default namespace that is
34 presented consists of only the user's personal mailboxes. To access
35 shared mailboxes, the user must use an escape mechanism to reach
38 The "Complete Hierarchy" model, in which the default namespace that
39 is presented includes the user's personal mailboxes along with any
40 other mailboxes they have access to.
42 These two models, create difficulties for certain client operations.
43 This document defines a NAMESPACE command that allows a client to
44 discover the prefixes of namespaces used by a server for personal
45 mailboxes, other users' mailboxes, and shared mailboxes. This allows
46 a client to avoid much of the manual user configuration that is now
47 necessary when mixing and matching IMAP4 clients and servers.
492. Conventions used in this document
51 In examples, "C:" and "S:" indicate lines sent by the client and
52 server respectively. If such lines are wrapped without a new "C:" or
53 "S:" label, then the wrapping is for editorial clarity and is not
58Gahrns & Newman Standards Track [Page 1]
60RFC 2342 IMAP4 Namespace May 1998
63 Personal Namespace: A namespace that the server considers within the
64 personal scope of the authenticated user on a particular connection.
65 Typically, only the authenticated user has access to mailboxes in
66 their Personal Namespace. It is the part of the namespace that
67 belongs to the user that is allocated for mailboxes. If an INBOX
68 exists for a user, it MUST appear within the user's personal
69 namespace. In the typical case, there SHOULD be only one Personal
70 Namespace on a server.
72 Other Users' Namespace: A namespace that consists of mailboxes from
73 the Personal Namespaces of other users. To access mailboxes in the
74 Other Users' Namespace, the currently authenticated user MUST be
75 explicitly granted access rights. For example, it is common for a
76 manager to grant to their secretary access rights to their mailbox.
77 In the typical case, there SHOULD be only one Other Users' Namespace
80 Shared Namespace: A namespace that consists of mailboxes that are
81 intended to be shared amongst users and do not exist within a user's
84 The namespaces a server uses MAY differ on a per-user basis.
86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
88 document are to be interpreted as described in [RFC-2119].
903. Introduction and Overview
92 Clients often attempt to create mailboxes for such purposes as
93 maintaining a record of sent messages (e.g. "Sent Mail") or
94 temporarily saving messages being composed (e.g. "Drafts"). For
95 these clients to inter-operate correctly with the variety of IMAP4
96 servers available, the user must enter the prefix of the Personal
97 Namespace used by the server. Using the NAMESPACE command, a client
98 is able to automatically discover this prefix without manual user
101 In addition, users are often required to manually enter the prefixes
102 of various namespaces in order to view the mailboxes located there.
103 For example, they might be required to enter the prefix of #shared to
104 view the shared mailboxes namespace. The NAMESPACE command allows a
105 client to automatically discover the namespaces that are available on
106 a server. This allows a client to present the available namespaces to
107 the user in what ever manner it deems appropriate. For example, a
114Gahrns & Newman Standards Track [Page 2]
116RFC 2342 IMAP4 Namespace May 1998
119 client could choose to initially display only personal mailboxes, or
120 it may choose to display the complete list of mailboxes available,
121 and initially position the user at the root of their Personal
124 A server MAY choose to make available to the NAMESPACE command only a
125 subset of the complete set of namespaces the server supports. To
126 provide the ability to access these namespaces, a client SHOULD allow
127 the user the ability to manually enter a namespace prefix.
131 IMAP4 servers that support this extension MUST list the keyword
132 NAMESPACE in their CAPABILITY response.
134 The NAMESPACE command is valid in the Authenticated and Selected
141 Response: an untagged NAMESPACE response that contains the prefix
142 and hierarchy delimiter to the server's Personal
143 Namespace(s), Other Users' Namespace(s), and Shared
144 Namespace(s) that the server wishes to expose. The
145 response will contain a NIL for any namespace class
146 that is not available. Namespace_Response_Extensions
147 MAY be included in the response.
148 Namespace_Response_Extensions which are not on the IETF
149 standards track, MUST be prefixed with an "X-".
151 Result: OK - Command completed
152 NO - Error: Can't complete command
153 BAD - argument invalid
158 < A server that supports a single personal namespace. No leading
159 prefix is used on personal mailboxes and "/" is the hierarchy
163 S: * NAMESPACE (("" "/")) NIL NIL
164 S: A001 OK NAMESPACE command completed
170Gahrns & Newman Standards Track [Page 3]
172RFC 2342 IMAP4 Namespace May 1998
178 < A user logged on anonymously to a server. No personal mailboxes
179 are associated with the anonymous user and the user does not have
180 access to the Other Users' Namespace. No prefix is required to
181 access shared mailboxes and the hierarchy delimiter is "." >
184 S: * NAMESPACE NIL NIL (("" "."))
185 S: A001 OK NAMESPACE command completed
190 < A server that contains a Personal Namespace and a single Shared
194 S: * NAMESPACE (("" "/")) NIL (("Public Folders/" "/"))
195 S: A001 OK NAMESPACE command completed
200 < A server that contains a Personal Namespace, Other Users'
201 Namespace and multiple Shared Namespaces. Note that the hierarchy
202 delimiter used within each namespace can be different. >
205 S: * NAMESPACE (("" "/")) (("~" "/")) (("#shared/" "/")
206 ("#public/" "/")("#ftp/" "/")("#news." "."))
207 S: A001 OK NAMESPACE command completed
209 The prefix string allows a client to do things such as automatically
210 creating personal mailboxes or LISTing all available mailboxes within
216 < A server that supports only the Personal Namespace, with a
217 leading prefix of INBOX to personal mailboxes and a hierarchy
221 S: * NAMESPACE (("INBOX." ".")) NIL NIL
222 S: A001 OK NAMESPACE command completed
226Gahrns & Newman Standards Track [Page 4]
228RFC 2342 IMAP4 Namespace May 1998
231 < Automatically create a mailbox to store sent items.>
233 C: A002 CREATE "INBOX.Sent Mail"
234 S: A002 OK CREATE command completed
236 Although typically a server will support only a single Personal
237 Namespace, and a single Other User's Namespace, circumstances exist
238 where there MAY be multiples of these, and a client MUST be prepared
239 for them. If a client is configured such that it is required to
240 create a certain mailbox, there can be circumstances where it is
241 unclear which Personal Namespaces it should create the mailbox in.
242 In these situations a client SHOULD let the user select which
243 namespaces to create the mailbox in.
248 < In this example, a server supports 2 Personal Namespaces. In
249 addition to the regular Personal Namespace, the user has an
250 additional personal namespace to allow access to mailboxes in an
251 MH format mailstore. >
253 < The client is configured to save a copy of all mail sent by the
254 user into a mailbox called 'Sent Mail'. Furthermore, after a
255 message is deleted from a mailbox, the client is configured to
256 move that message to a mailbox called 'Deleted Items'.>
258 < Note that this example demonstrates how some extension flags can
259 be passed to further describe the #mh namespace. >
262 S: * NAMESPACE (("" "/")("#mh/" "/" "X-PARAM" ("FLAG1" "FLAG2")))
264 S: A001 OK NAMESPACE command completed
266 < It is desired to keep only one copy of sent mail. It is unclear
267 which Personal Namespace the client should use to create the 'Sent
268 Mail' mailbox. The user is prompted to select a namespace and
269 only one 'Sent Mail' mailbox is created. >
271 C: A002 CREATE "Sent Mail"
272 S: A002 OK CREATE command completed
274 < The client is designed so that it keeps two 'Deleted Items'
275 mailboxes, one for each namespace. >
277 C: A003 CREATE "Delete Items"
278 S: A003 OK CREATE command completed
282Gahrns & Newman Standards Track [Page 5]
284RFC 2342 IMAP4 Namespace May 1998
287 C: A004 CREATE "#mh/Deleted Items"
288 S: A004 OK CREATE command completed
290 The next level of hierarchy following the Other Users' Namespace
291 prefix SHOULD consist of <username>, where <username> is a user name
292 as per the IMAP4 LOGIN or AUTHENTICATE command.
294 A client can construct a LIST command by appending a "%" to the Other
295 Users' Namespace prefix to discover the Personal Namespaces of other
296 users that are available to the currently authenticated user.
298 In response to such a LIST command, a server SHOULD NOT return user
299 names that have not granted access to their personal mailboxes to the
302 A server MAY return a LIST response containing only the names of
303 users that have explicitly granted access to the user in question.
305 Alternatively, a server MAY return NO to such a LIST command,
306 requiring that a user name be included with the Other Users'
307 Namespace prefix before listing any other user's mailboxes.
312 < A server that supports providing a list of other user's
313 mailboxes that are accessible to the currently logged on user. >
316 S: * NAMESPACE (("" "/")) (("Other Users/" "/")) NIL
317 S: A001 OK NAMESPACE command completed
319 C: A002 LIST "" "Other Users/%"
320 S: * LIST () "/" "Other Users/Mike"
321 S: * LIST () "/" "Other Users/Karen"
322 S: * LIST () "/" "Other Users/Matthew"
323 S: * LIST () "/" "Other Users/Tesa"
324 S: A002 OK LIST command completed
329 < A server that does not support providing a list of other user's
330 mailboxes that are accessible to the currently logged on user.
331 The mailboxes are listable if the client includes the name of the
332 other user with the Other Users' Namespace prefix. >
338Gahrns & Newman Standards Track [Page 6]
340RFC 2342 IMAP4 Namespace May 1998
344 S: * NAMESPACE (("" "/")) (("#Users/" "/")) NIL
345 S: A001 OK NAMESPACE command completed
347 < In this example, the currently logged on user has access to the
348 Personal Namespace of user Mike, but the server chose to suppress
349 this information in the LIST response. However, by appending the
350 user name Mike (received through user input) to the Other Users'
351 Namespace prefix, the client is able to get a listing of the
352 personal mailboxes of user Mike. >
354 C: A002 LIST "" "#Users/%"
355 S: A002 NO The requested item could not be found.
357 C: A003 LIST "" "#Users/Mike/%"
358 S: * LIST () "/" "#Users/Mike/INBOX"
359 S: * LIST () "/" "#Users/Mike/Foo"
360 S: A003 OK LIST command completed.
362 A prefix string might not contain a hierarchy delimiter, because
363 in some cases it is not needed as part of the prefix.
368 < A server that allows access to the Other Users' Namespace by
369 prefixing the others' mailboxes with a '~' followed by <username>,
370 where <username> is a user name as per the IMAP4 LOGIN or
371 AUTHENTICATE command.>
374 S: * NAMESPACE (("" "/")) (("~" "/")) NIL
375 S: A001 OK NAMESPACE command completed
377 < List the mailboxes for user mark >
379 C: A002 LIST "" "~mark/%"
380 S: * LIST () "/" "~mark/INBOX"
381 S: * LIST () "/" "~mark/foo"
382 S: A002 OK LIST command completed
384 Historical convention has been to start all namespaces with the "#"
385 character. Namespaces that include the "#" character are not IMAP
386 URL [IMAP-URL] friendly requiring the "#" character to be represented
387 as %23 when within URLs. As such, server implementers MAY instead
388 consider using namespace prefixes that do not contain the "#"
394Gahrns & Newman Standards Track [Page 7]
396RFC 2342 IMAP4 Namespace May 1998
401 The following syntax specification uses the augmented Backus-Naur
402 Form (BNF) as described in [ABNF].
405 ; <atom> as defined in [RFC-2060]
407 Namespace = nil / "(" 1*( "(" string SP (<"> QUOTED_CHAR <"> /
408 nil) *(Namespace_Response_Extension) ")" ) ")"
412 Namespace_Response_Extension = SP string SP "(" string *(SP string)
418 ; The first Namespace is the Personal Namespace(s)
419 ; The second Namespace is the Other Users' Namespace(s)
420 ; The third Namespace is the Shared Namespace(s)
423 ; <nil> as defined in [RFC-2060]
425 QUOTED_CHAR = <QUOTED_CHAR>
426 ; <QUOTED_CHAR> as defined in [RFC-2060]
429 ; <string> as defined in [RFC-2060]
430 ; Note that the namespace prefix is to a mailbox and following
431 ; IMAP4 convention, any international string in the NAMESPACE
432 ; response MUST be of modified UTF-7 format as described in
4357. Security Considerations
437 In response to a LIST command containing an argument of the Other
438 Users' Namespace prefix, a server SHOULD NOT list users that have not
439 granted list access to their personal mailboxes to the currently
440 authenticated user. Providing such a list, could compromise security
441 by potentially disclosing confidential information of who is located
442 on the server, or providing a starting point of a list of user
450Gahrns & Newman Standards Track [Page 8]
452RFC 2342 IMAP4 Namespace May 1998
457 [RFC-2060], Crispin, M., "Internet Message Access Protocol Version
458 4rev1", RFC 2060, December 1996.
460 [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate
461 Requirement Levels", BCP 14, RFC 2119, March 1997.
463 [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for Syntax
464 Specifications: ABNF", RFC 2234, November 1997.
466 [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, September 1997.
470 Many people have participated in the discussion of IMAP namespaces on
471 the IMAP mailing list. In particular, the authors would like to
472 thank Mark Crispin for many of the concepts relating to the Personal
473 Namespace and accessing the Personal Namespace of other users, Steve
474 Hole for summarizing the two namespace models, John Myers and Jack De
475 Winter for their work in a preceding effort trying to define a
476 standardized personal namespace, and Larry Osterman for his review
477 and collaboration on this document.
47911. Authors' Addresses
484 Redmond, WA, 98072, USA
486 Phone: (425) 936-9833
487 EMail: mikega@microsoft.com
491 Innosoft International, Inc.
492 1050 East Garvey Ave. South
493 West Covina, CA, 91790, USA
495 EMail: chris.newman@innosoft.com
506Gahrns & Newman Standards Track [Page 9]
508RFC 2342 IMAP4 Namespace May 1998
51112. Full Copyright Statement
513 Copyright (C) The Internet Society (1998). All Rights Reserved.
515 This document and translations of it may be copied and furnished to
516 others, and derivative works that comment on or otherwise explain it
517 or assist in its implementation may be prepared, copied, published
518 and distributed, in whole or in part, without restriction of any
519 kind, provided that the above copyright notice and this paragraph are
520 included on all such copies and derivative works. However, this
521 document itself may not be modified in any way, such as by removing
522 the copyright notice or references to the Internet Society or other
523 Internet organizations, except as needed for the purpose of
524 developing Internet standards in which case the procedures for
525 copyrights defined in the Internet Standards process must be
526 followed, or as required to translate it into languages other than
529 The limited permissions granted above are perpetual and will not be
530 revoked by the Internet Society or its successors or assigns.
532 This document and the information contained herein is provided on an
533 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
534 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
535 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
536 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
537 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
562Gahrns & Newman Standards Track [Page 10]