RFC 2342

IMAP4 Namespace

📅 published May 1998, from ietf

RFC 2342: IMAP4 Namespace 🎀

Part 1 of 3, more to come 💖

Okay bestie, so this is RFC 2342, called IMAP4 Namespace ✨. It was written by M. Gahrns from Microsoft and C. Newman from Innosoft. It's a Standards Track doc from May 1998. The title block doesn't list anything it obsoletes or updates, so there's no drama there 💅

Status of This Memo 📜

This doc specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions to make it better 🫶 For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share away 🦋

Copyright (C) The Internet Society (1998). All Rights Reserved.

1. Abstract ✨

Okay so IMAP4 [RFC-2060] doesn't define a default server namespace, and that's lowkey the root of the chaos 💀 Because of that, two common namespace models have popped off:

"Personal Mailbox": the default namespace you see only has your personal mailboxes. If you want shared mailboxes, you have to use some escape mechanism to get to a different namespace 🙈

"Complete Hierarchy": the default namespace you see includes your personal mailboxes plus every other mailbox you have access to 🌈

Both of these models create difficulties for certain client operations, and honestly it's giving headache 😭 This document defines a NAMESPACE command so a client can discover the prefixes of the namespaces a server uses for personal mailboxes, other users' mailboxes, and shared mailboxes. That means a client can skip a lot of the manual setup users currently have to do when they mix and match IMAP4 clients and servers 🧚

2. Conventions used in this document 📖

In examples, C: and S: mark lines sent by the client and server. If those lines get wrapped without a new C: or S: label, the wrap is just for editorial clarity and isn't part of the command 🍓

Personal Namespace: a namespace the server considers to be within the personal scope of the authenticated user on a particular connection. Usually only the authenticated user can access mailboxes in their Personal Namespace. It's the part of the namespace that belongs to the user and is set aside for their mailboxes. If an INBOX exists for a user, it MUST appear within that user's personal namespace. In the typical case, there SHOULD be only one Personal Namespace on a server 👑

Other Users' Namespace: a namespace made up of mailboxes from the Personal Namespaces of other users. To access mailboxes in the Other Users' Namespace, the currently authenticated user MUST be explicitly granted access rights. For example, it's super common for a manager to give their secretary access to their mailbox 💼 In the typical case, there SHOULD be only one Other Users' Namespace on a server ✨

Shared Namespace: a namespace made up of mailboxes that are meant to be shared among users and that don't exist within a user's Personal Namespace 🫂

The namespaces a server uses MAY differ on a per-user basis 🌸

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] 🎀

3. Introduction and Overview 🌸

Clients love making their own mailboxes for stuff like keeping a record of sent messages (for example "Sent Mail") or temporarily saving messages being composed (for example "Drafts") 💌 For these clients to work correctly with all the different IMAP4 servers out there, the user has to type in the prefix of the Personal Namespace the server uses. With the NAMESPACE command, a client can find that prefix automatically, so no manual typing needed 🙌

Users also often have to manually type in the prefixes of various namespaces just to see the mailboxes sitting there. For example, they might have to type #shared to see the shared mailboxes namespace 😩 The NAMESPACE command lets a client automatically discover which namespaces are available on a server. That way the client can show them to the user however it thinks is best. For example, a client could start out showing only personal mailboxes, or it could show the whole list of available mailboxes and put the user right at the root of their Personal Namespace 🦋

A server MAY choose to make only a subset of the namespaces it supports available to the NAMESPACE command. To still let users reach the rest, a client SHOULD let the user manually type in a namespace prefix 🔥

4. Requirements 💅

IMAP4 servers that support this extension MUST list the keyword NAMESPACE in their CAPABILITY response 🧚‍♀️

The NAMESPACE command is valid in the Authenticated and Selected state 👑

5. NAMESPACE Command ✨

okay so the NAMESPACE command takes no arguments 🎀 you just send it and the server replies with an untagged NAMESPACE response that lists the prefix and hierarchy delimiter for the Personal Namespace(s), the Other Users' Namespace(s), and the Shared Namespace(s) it wants to show off 💅. If a namespace class isn't available, the server puts a NIL in that slot 🙈 and Namespace_Response_Extensions MAY be included too. Any extension that is not on the IETF standards track MUST be prefixed with an "X-" 🔥

Results are super simple: OK means the command completed ✨, NO means something went wrong and the command couldn't be completed 💀, and BAD means the argument was invalid (which, lol, there are no arguments, so good luck 😭).

  • OK - Command completed
  • NO - Error: Can't complete command
  • BAD - argument invalid

Example 5.1:

< A server that supports a single personal namespace.  No leading
prefix is used on personal mailboxes and "/" is the hierarchy
delimiter.>

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) NIL NIL
S: A001 OK NAMESPACE command completed

Example 5.2:

< A user logged on anonymously to a server.  No personal mailboxes
are associated with the anonymous user and the user does not have
access to the Other Users' Namespace.  No prefix is required to
access shared mailboxes and the hierarchy delimiter is "." >

C: A001 NAMESPACE
S: * NAMESPACE NIL NIL (("" "."))
S: A001 OK NAMESPACE command completed

Example 5.3:

< A server that contains a Personal Namespace and a single Shared
Namespace. >

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) NIL (("Public Folders/" "/"))
S: A001 OK NAMESPACE command completed

Example 5.4:

< A server that contains a Personal Namespace, Other Users'
Namespace and multiple Shared Namespaces.  Note that the hierarchy
delimiter used within each namespace can be different. >

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) (("~" "/")) (("#shared/" "/")
   ("#public/" "/")("#ftp/" "/")("#news." "."))
S: A001 OK NAMESPACE command completed

The prefix string is the magic bit 🧚 because it lets a client do things like auto-creating personal mailboxes or LISTing every mailbox inside a namespace 💖

Example 5.5:

< A server that supports only the Personal Namespace, with a
leading prefix of INBOX to personal mailboxes and a hierarchy
delimiter of ".">

C: A001 NAMESPACE
S: * NAMESPACE (("INBOX." ".")) NIL  NIL
S: A001 OK NAMESPACE command completed
< Automatically create a mailbox to store sent items.>

C: A002 CREATE "INBOX.Sent Mail"
S: A002 OK CREATE command completed

Okay now the plot thickens 🌈 Usually a server only has one Personal Namespace and one Other User's Namespace, BUT there are situations where there MAY be multiples of these, and a client MUST be prepared for them 😤 If a client is set up to create a certain mailbox and it's genuinely unclear which Personal Namespace to put it in, a client SHOULD let the user pick which namespaces to create the mailbox in. Main character decision-making 👑

Example 5.6:

< In this example, a server supports 2 Personal Namespaces.  In
addition to the regular Personal Namespace, the user has an
additional personal namespace to allow access to mailboxes in an
MH format mailstore. >

< The client is configured to save a copy of all mail sent by the
user into a mailbox called 'Sent Mail'.  Furthermore, after a
message is deleted from a mailbox, the client is configured to
move that message to a mailbox called 'Deleted Items'.>

< Note that this example demonstrates how some extension flags can
be passed to further describe the #mh namespace. >

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")("#mh/" "/" "X-PARAM" ("FLAG1" "FLAG2")))
   NIL NIL
S: A001 OK NAMESPACE command completed

< It is desired to keep only one copy of sent mail. It is unclear
which Personal Namespace the client should use to create the 'Sent
Mail' mailbox.  The user is prompted to select a namespace and
only one 'Sent Mail' mailbox is created. >

C: A002 CREATE "Sent Mail"
S: A002 OK CREATE command completed

< The client is designed so that it keeps two 'Deleted Items'
mailboxes, one for each namespace. >

C: A003 CREATE "Delete Items"
S: A003 OK CREATE command completed
C: A004 CREATE "#mh/Deleted Items"
S: A004 OK CREATE command completed

The next level of hierarchy after the Other Users' Namespace prefix SHOULD consist of <username>, and that <username> is a user name as per the IMAP4 LOGIN or AUTHENTICATE command 🫶

Clients can also build a LIST command by slapping a "%" onto the end of the Other Users' Namespace prefix 🦋 That's how you go hunting for the Personal Namespaces of other users that the currently authenticated user is allowed to see 👀

Now the tea ☕ When the server answers that LIST, it SHOULD NOT return user names that haven't granted access to their personal mailboxes to the user asking 🙅‍♀️ Wild, right? The server MAY also return a LIST response with only the names of users who have explicitly granted access to that user. Or, plot twist, the server MAY return NO to that LIST command, which means a user name has to be included with the Other Users' Namespace prefix before any other user's mailboxes can be listed 🔒

Example 5.7:

< A server that supports providing a list of other user's
mailboxes that are accessible to the currently logged on user. >

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) (("Other Users/" "/")) NIL
S: A001 OK NAMESPACE command completed

C: A002 LIST "" "Other Users/%"
S: * LIST () "/" "Other Users/Mike"
S: * LIST () "/" "Other Users/Karen"
S: * LIST () "/" "Other Users/Matthew"
S: * LIST () "/" "Other Users/Tesa"
S: A002 OK LIST command completed

Example 5.8:

< A server that does not support providing a list of other user's
mailboxes that are accessible to the currently logged on user.
The mailboxes are listable if the client includes the name of the
other user with the Other Users' Namespace prefix. >
C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) (("#Users/" "/")) NIL
S: A001 OK NAMESPACE command completed

< In this example, the currently logged on user has access to the
Personal Namespace of user Mike, but the server chose to suppress
this information in the LIST response.  However, by appending the
user name Mike (received through user input) to the Other Users'
Namespace prefix, the client is able to get a listing of the
personal mailboxes of user Mike. >

C: A002 LIST "" "#Users/%"
S: A002 NO The requested item could not be found.

C: A003 LIST "" "#Users/Mike/%"
S: * LIST () "/" "#Users/Mike/INBOX"
S: * LIST () "/" "#Users/Mike/Foo"
S: A003 OK LIST command completed.

A prefix string doesn't always have to include a hierarchy delimiter, since sometimes it just isn't needed as part of the prefix 🌸

Example 5.9:

< A server that allows access to the Other Users' Namespace by
prefixing the others' mailboxes with a '~' followed by <username>,
where <username> is a user name as per the IMAP4 LOGIN or
AUTHENTICATE command.>

C: A001 NAMESPACE
S: * NAMESPACE (("" "/")) (("~" "/")) NIL
S: A001 OK NAMESPACE command completed

< List the mailboxes for user mark >

C: A002 LIST "" "~mark/%"
S: * LIST () "/" "~mark/INBOX"
S: * LIST () "/" "~mark/foo"
S: A002 OK LIST command completed

Historically, everyone started their namespaces with the "#" character 💅 But namespaces that include "#" aren't IMAP URL [IMAP-URL] friendly, because inside URLs that "#" has to be written as %23 🙈 So server implementers MAY instead consider namespace prefixes that don't contain the "#" character ✨

6. Formal Syntax 💅

The syntax below is written in augmented Backus-Naur Form (BNF) as described in [ABNF] 🧁 Here's the grammar, copied exactly as it appears:

atom = <atom>
   ; <atom> as defined in [RFC-2060]

Namespace = nil / "(" 1*( "(" string SP  (<"> QUOTED_CHAR <"> /
   nil) *(Namespace_Response_Extension) ")" ) ")"

Namespace_Command = "NAMESPACE"

Namespace_Response_Extension = SP string SP "(" string *(SP string)
   ")"

Namespace_Response = "*" SP "NAMESPACE" SP Namespace SP Namespace SP
   Namespace

   ; The first Namespace is the Personal Namespace(s)
   ; The second Namespace is the Other Users' Namespace(s)
   ; The third Namespace is the Shared Namespace(s)

   nil = <nil>
      ; <nil> as defined in [RFC-2060]

   QUOTED_CHAR = <QUOTED_CHAR>
      ; <QUOTED_CHAR> as defined in [RFC-2060]

   string = <string>
      ; <string> as defined in [RFC-2060]
      ; Note that  the namespace prefix is to a mailbox and following
      ; IMAP4 convention, any international string in the NAMESPACE
      ; response MUST be of modified UTF-7 format as described in
      ;  [RFC-2060].

Quick heads up on that last comment 👀: any international string in the NAMESPACE response MUST be modified UTF-7 format, as described in [RFC-2060]. No skipping that one bestie 🫶

7. Security Considerations 🔐

🚨 Okay this one is SERIOUS, so read it twice. In response to a LIST command that uses the Other Users' Namespace prefix as its argument, a server SHOULD NOT list users who haven't granted list access to their personal mailboxes to the currently authenticated user. Handing out that list could compromise security, because it might reveal confidential info about who is on the server, or give an attacker a starting point for a list of user accounts to go after 💀

8. References 📚

[RFC-2060], Crispin, M., "Internet Message Access Protocol Version 4rev1", RFC 2060, December 1996.

[RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.

[IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, September 1997.

9. Acknowledgments 🫶

So many people talked about IMAP namespaces on the IMAP mailing list 💜 The authors especially want to thank Mark Crispin for a lot of the ideas about the Personal Namespace and accessing other users' Personal Namespaces 🌈 Steve Hole gets a shout-out for summarizing the two namespace models 🙌 John Myers and Jack De Winter get love for their work on an earlier effort to define a standardized personal namespace 🦋 And Larry Osterman gets a huge thank you for reviewing and collaborating on this document ✨

11. Authors' Addresses 🎀

Mike Gahrns Microsoft One Microsoft Way Redmond, WA, 98072, USA

Phone: (425) 936-9833 EMail: mikega@microsoft.com

Chris Newman Innosoft International, Inc. 1050 East Garvey Ave. South West Covina, CA, 91790, USA

EMail: chris.newman@innosoft.com

Copyright (C) The Internet Society (1998). All Rights Reserved. 🌈

okay bestie, the legal bit is actually pretty chill 💅 You're allowed to copy and share this doc, along with translations of it. You can also make derivative works that comment on it, explain it, or help people implement it, and you can publish and distribute those too, in whole or in part, with no restrictions at all. The one catch is that the copyright notice and this paragraph have to stay on every copy and every derivative work 🫶

The original document itself is a different story. It may not be modified in any way. That means no removing the copyright notice, and no removing references to the Internet Society or other Internet organizations. There are two exceptions. The first is developing Internet standards, where the copyright procedures in the Internet Standards process must be followed. The second is translating it into languages other than English 🌸

The permissions above are perpetual. The Internet Society, its successors, and its assigns will never revoke them 🦋

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💀

📦 where this page comes from