RFC 2193

IMAP4 Mailbox Referrals 🎀

Okay bestie, let's start with the title block 💅 This one is from M. Gahrns at Microsoft, filed under Standards Track, dated September 1997. It's from the Network Working Group and it doesn't list anything it obsoletes or updates, so no drama there 🦋

Status of this Memo ✨

Okay so this is the boring-but-important bit. It's an Internet standards track protocol spec for the Internet community, and it's asking for discussion and suggestions for improvements 🫶 For the current standardization state, check the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌸

1. Abstract 💖

Okay, picture this: loads and loads of users, messages, and geographically spread-out IMAP4 [RFC-2060] servers inside one organization. It's giving "we need to spread the messages around" 😭 For example, an admin might keep your personal mailbox on a local IMAP4 server and park shared mailboxes on a different server far away. This is super common when it's too expensive to store everything in one central spot because bandwidth or disk space is tight 💅

Mailbox referrals let clients reach mailboxes spread across several IMAP4 servers seamlessly ✨

Now the alternative is the "proxy method" 🙈 In that one, the local IMAP4 server contacts the remote server for the client, pulls the data from the remote server, and then passes it along to the client. The referral mechanism is often more efficient bandwidth-wise, because the client connects directly to the remote server 🦋 It also means the local server doesn't have to impersonate the client when it logs in to the remote server. Iconic, right? 👑

2. Conventions used in this document 🌈

In examples, "C:" means lines the client sent and "S:" means lines the server sent 💜

A home server is an IMAP4 server that holds the user's inbox 🏠

A remote mailbox is a mailbox that is not hosted on the user's home server 🧳

A remote server is a server that holds remote mailboxes 🛰️

A shared mailbox is a mailbox that multiple users can access 🫂

An IMAP mailbox referral is when the server points the client over to a different IMAP mailbox 👉

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in [RFC-2119] 🎀 These are the official capital-letter vibes, so pay attention to them 😤

3. Introduction and Overview 🧚

Okay, the big rule: IMAP4 servers that support this extension MUST list the keyword MAILBOX-REFERRALS in their CAPABILITY response 💖 The best part is that the client doesn't have to do anything to turn the MAILBOX-REFERRALS capability on in a server ✨

A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals that result in a referrals loop 🙅‍♀️ No infinite ping-pong, bestie 💀

A referral response is a tagged NO response with a REFERRAL response code. The REFERRAL response code MUST contain, as an argument, a one or more valid URLs separated by a space, as defined in [RFC-1738] 🍓 If the server gives multiple URLs for one object, they MUST all be the same type. When that happens, the URL MUST be an IMAP URL as defined in [RFC-2192]. A client that supports the REFERRALS extension MUST be ready for a URL of any type, but it only needs to be able to process IMAP URLs 🌸

A server MAY respond with multiple IMAP mailbox referrals if there's more than one replica of the mailbox. This is how you get load balancing or failover, which is so smart 🧠 How a server keeps those replicas in sync is not covered by this document 🤷‍♀️

If the server has a preferred order for the client to try the URLs, the preferred URL SHOULD be listed first, with the rest in descending order of preference 👑 If a mailbox gets multiple referrals, a server should be aware that clients can run into synchronization issues if the UIDVALIDITY of the referred mailboxes is different ⚠️

An IMAP mailbox referral may be given in response to any IMAP command that takes a mailbox as an argument 💅

Example:

A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox

NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a client falling back to anonymous login 🙈

Okay, here's the tea: remote mailboxes (and their inferiors) that are only reachable through referrals SHOULD NOT show up in LIST and LSUB responses from the user's home server 🫣 They MUST show up in RLIST and RLSUB responses from the user's home server 💖 Hierarchy referrals, where a client has to connect to the remote server just to LIST and find a mailbox's inferiors, are not covered in this document 🚫

For example, if shared mailboxes were only reachable through referrals on a remote server, an RLIST "" "#SHARED/%" command would return the same response whether it's sent to the user's home server or to the remote server ✨

Note: mailboxes on the user's home server don't need to exist on the remote server too 🏡 There might also be extra mailboxes on the remote server, but the client won't be able to reach them through referrals unless they appear in the LIST response to the RLIST command sent to the home server 👀

A MAILBOX-REFERRALS capable client sends RLIST and RLSUB instead of LIST and LSUB 🦋 RLIST and RLSUB work exactly like their LIST and LSUB counterparts, except remote mailboxes get returned along with the local ones in the LIST and LSUB responses. This keeps unreachable remote mailboxes from showing up for a client that isn't MAILBOX-REFERRALS enabled 🙈

4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND Referrals 🌟

An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS, or APPEND command with one or more IMAP mailbox referrals to tell the client the mailbox is hosted on a remote server 🧚‍♀️

When a client processes an IMAP mailbox referral, it opens a new connection, or reuses an existing one, to the remote server so it can issue the commands needed to handle the remote mailbox 💖

Example:

<IMAP4 connection to home server>

   C: A001 DELETE "SHARED/FOO"
   S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
          Remote mailbox. Try SERVER2.

   <Client established a second connection to SERVER2 and
   issues the DELETE command on the referred mailbox>

   S: * OK IMAP4rev1 server ready
   C: B001 AUTHENTICATE KERBEROS_V4
   <authentication exchange>
   S: B001 OK user is authenticated

   C: B002 DELETE "SHARED/FOO"
   S: B002 OK DELETE completed

Example:

<IMAP4 connection to home server>

   C: A001 SELECT REMOTE
   S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE
       IMAP://user;AUTH=*@SERVER3/REMOTE] Remote mailbox.
       Try SERVER2 or SERVER3.

   <Client opens second connection to remote server, and
    issues the commands needed to process the items in the
    remote mailbox>

   S: * OK IMAP4rev1 server ready
   C: B001 AUTHENTICATE KERBEROS_V4
   <authentication exchange>
   S: B001 OK user is authenticated

   C: B002 SELECT REMOTE
   S: * 12 EXISTS
   S: * 1 RECENT
   S: * OK [UNSEEN 10] Message 10 is first unseen
   S: * OK [UIDVALIDITY 123456789]
   S: * FLAGS (Answered Flagged Deleted Seen Draft)
   S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
   S: B002 OK [READ-WRITE] Selected completed

   C: B003 FETCH 10:12 RFC822
   S: * 10 FETCH . . .
   S: * 11 FETCH . . .
   S: * 12 FETCH . . .
   S: B003 OK FETCH Completed
   <Client is finished processing the REMOTE mailbox and
    wants to process a mailbox on its home server>

   C: B004 LOGOUT
   S: * BYE IMAP4rev1 server logging out
   S: B004 OK LOGOUT Completed

   <Client continues with first connection>

   C: A002 SELECT INBOX
   S: * 16 EXISTS
   S: * 2 RECENT
   S: * OK [UNSEEN 10] Message 10 is first unseen
   S: * OK [UIDVALIDITY 123456789]
   S: * FLAGS (Answered Flagged Deleted Seen Draft)
   S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
   S: A002 OK [READ-WRITE] Selected completed

4.2. CREATE Referrals 🎀

An IMAP4 server MAY respond to the CREATE command with one or more IMAP mailbox referrals, if it wants to send the client over to another server to run the CREATE there 🚀 The server can use any method to decide which server the mailbox should be created on, like looking at the hierarchy of the mailbox name 🧠

Example:

C: A001 CREATE "SHARED/FOO"
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
   Mailbox should be created on remote server

Alternatively, since a home server is required to keep a listing of referred remote mailboxes, a server MAY allow a mailbox that will eventually live on a remote server to be created against the home server. Then it can provide referrals on later commands that work with that mailbox 💅

Example:

C: A001 CREATE "SHARED/FOO"
S: A001 OK CREATE succeeded

C: A002 SELECT "SHARED/FOO"
S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
   Remote mailbox.  Try SERVER2

4.3. RENAME Referrals 🦋

An IMAP4 server MAY respond to the RENAME command with one or more pairs of IMAP mailbox referrals. In each pair, the first referral is a URL for the existing mailbox name, and the second is a URL for the requested new mailbox name 👯‍♀️

If the existing and new mailbox URLs in a pair are on different servers, the remote servers can't do the RENAME operation 😭 To get the same result as a server RENAME, the client MAY issue the constituent CREATE, FETCH, APPEND, and DELETE commands against both servers 🔁

If the existing and new mailbox URLs in a pair are on the same server, that tells you the currently connected server can't do the operation 🙅‍♀️ The client can just re-issue the RENAME command on the remote server 💖

Example:

C: A001 RENAME FOO BAR
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER1/FOO
        IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
        across servers

Since the existing and new mailbox names are on different servers, the client would have to connect to both servers and issue the constituent commands required to get the RENAME done 🫠

Example:

C: A001 RENAME FOO BAR
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/FOO
        IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
        located on SERVER2

Since both the existing and new mailbox are on the same remote server, the client can simply connect to the remote server and re-issue the RENAME command ✨

4.4. COPY Referrals 🌸

An IMAP4 server MAY respond to the COPY command with one or more IMAP mailbox referrals. This means the destination mailbox is on a remote server 🛰️ To get the same result as a server COPY, the client MAY issue the constituent FETCH and APPEND commands against both servers 🫶

Example:

C: A001 COPY 1 "SHARED/STUFF"
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/STUFF]
        Unable to copy message(s) to SERVER2.

5.1. RLIST command 🎀

okay so bestie, RLIST is basically the LIST command's glow-up 💅. Arguments are a reference name and a mailbox name with possible wildcards, and the only untagged response is LIST.

The results are:

• OK - RLIST Completed ✨
• NO - RLIST Failure 💀
• BAD - command unknown or arguments invalid 🙈

The whole vibe is that RLIST behaves identically to LIST, EXCEPT remote mailboxes get returned too, alongside the local ones in the LIST responses. Main character energy 👑🦋

5.2. RLSUB Command 🌸

RLSUB is the same story but for LSUB 🫶. Arguments are a reference name and a mailbox name with possible wildcards, and the untagged response is LSUB.

The results are:

• OK - RLSUB Completed 🌈
• NO - RLSUB Failure 😭
• BAD - command unknown or arguments invalid 💜

It behaves identically to its LSUB counterpart, except remote mailboxes are returned in addition to local mailboxes in the LSUB responses. Iconic, periodt 💖

---

6. Formal Syntax 🧚

okay so this part is the grammar, and it's written in the augmented Backus-Naur Form (BNF) as described in [ABNF]. Let's look at it together 🍓

list_mailbox = <list_mailbox> as defined in [RFC-2060]

mailbox = <mailbox> as defined in [RFC-2060]

mailbox_referral = <tag> SPACE "NO" SPACE
   <referral_response_code> (text / text_mime2)
   ; See [RFC-2060] for <tag>, text and text_mime2 definition

referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]"
   ; See [RFC-1738] for <url> definition

rlist = "RLIST" SPACE mailbox SPACE list_mailbox

rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox

So list_mailbox and mailbox both just point back to [RFC-2060] for their definitions 🫶. The mailbox_referral is a tag, a SPACE, then "NO", then the referral_response_code and the text, and the referral_response_code is a bracketed "REFERRAL" followed by one or more URLs (defined in [RFC-1738]) 🔥. And RLIST and RLSUB are just the command name, a mailbox, and a list_mailbox ✨.

---

6. Security Considerations 🔐

ngl this section is the serious one, so pay attention bestie 😭

The IMAP4 referral mechanism makes use of IMAP URLs, and as such, has the same security considerations as general internet URLs [RFC-1738], and in particular IMAP URLs [RFC-2192].

With the MAILBOX-REFERRALS capability, it is potentially easier to write a rogue server that injects a bogus referral response that directs a user to an incorrect mailbox 💀. Although referrals reduce the effort to write such a server, the referral response makes detection of the intrusion easier 🕵️‍♀️. So it's a double-edged sword, literally 🗡️

---

7. References 📚

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

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

[RFC-1738], Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994.

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

[ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for Syntax Specifications: ABNF", Work in Progress, Internet Mail Consortium, April 1997.

---

8. Acknowledgments 🫶

bestie, so many valuable suggestions came from private discussions and the IMAP4 mailing list 💜. Special shoutout to Raymond Cheng, Mark Crispin, Mark Keasling, Chris Newman and Larry Osterman, who all made significant contributions to this document 👑✨

---

9. Author's Address 🦋

Mike Gahrns Microsoft One Microsoft Way Redmond, WA, 98072

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