IMAP4 Referrals: IMAP4 Mailbox Referrals
How an IMAP server can point a client to another server that holds a mailbox.
Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, DOI 10.17487/RFC2193, September 1997, <https://www.rfc-editor.org/info/rfc2193>.
@misc{rfc2193,
series = {Request for Comments},
number = 2193,
howpublished = {RFC 2193},
publisher = {RFC Editor},
doi = {10.17487/RFC2193},
url = {https://www.rfc-editor.org/info/rfc2193},
author = {M. Gahrns},
title = {{IMAP4 Mailbox Referrals}},
pagetotal = 9,
year = 1997,
month = sep,
} RFC text
Contents
Network Working Group M. Gahrns
Request for Comments: 2193 Microsoft
Category: Standards Track September 1997
IMAP4 Mailbox Referrals
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
1. Abstract
When dealing with large amounts of users, messages and geographically
dispersed IMAP4 [RFC-2060] servers, it is often desirable to
distribute messages amongst different servers within an organization.
For example an administrator may choose to store user's personal
mailboxes on a local IMAP4 server, while storing shared mailboxes
remotely on another server. This type of configuration is common
when it is uneconomical to store all data centrally due to limited
bandwidth or disk resources.
Mailbox referrals allow clients to seamlessly access mailboxes that
are distributed across several IMAP4 servers.
A referral mechanism can provide efficiencies over the alternative
"proxy method", in which the local IMAP4 server contacts the remote
server on behalf of the client, and then transfers the data from the
remote server to itself, and then on to the client. The referral
mechanism's direct client connection to the remote server is often a
more efficient use of bandwidth, and does not require the local
server to impersonate the client when authenticating to the remote
server.
2. Conventions used in this document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
A home server, is an IMAP4 server that contains 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 contains remote mailboxes.
A shared mailbox, is a mailbox that multiple users have access to.
An IMAP mailbox referral is when the server directs the client to
another 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 interpreted as described in [RFC-2119].
3. Introduction and Overview
IMAP4 servers that support this extension MUST list the keyword
MAILBOX-REFERRALS in their CAPABILITY response. No client action is
needed to invoke the MAILBOX-REFERRALS capability in a server.
A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals
that result in a referrals loop.
A referral response consists of a tagged NO response and 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 a server replies with multiple URLs for a particular
object, they MUST all be of the same type. In this case, the URL MUST
be an IMAP URL as defined in [RFC-2192]. A client that supports the
REFERRALS extension MUST be prepared for a URL of any type, but it
need only be able to process IMAP URLs.
A server MAY respond with multiple IMAP mailbox referrals if there is
more than one replica of the mailbox. This allows the implementation
of a load balancing or failover scheme. How a server keeps multiple
replicas of a mailbox in sync is not addressed by this document.
If the server has a preferred order in which the client should
attempt to access the URLs, the preferred URL SHOULD be listed in the
first, with the remaining URLs presented in descending order of
preference. If multiple referrals are given for a mailbox, a server
should be aware that there are synchronization issues for a client if
the UIDVALIDITY of the referred mailboxes are different.
An IMAP mailbox referral may be given in response to an IMAP command
that specifies 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.
Remote mailboxes and their inferiors, that are accessible only via
referrals SHOULD NOT appear in LIST and LSUB responses issued against
the user's home server. They MUST appear in RLIST and RLSUB
responses issued against the user's home server. Hierarchy referrals,
in which a client would be required to connect to the remote server
to issue a LIST to discover the inferiors of a mailbox are not
addressed in this document.
For example, if shared mailboxes were only accessible via referrals
on a remote server, a RLIST "" "#SHARED/%" command would return the
same response if issued against the user's home server or the remote
server.
Note: Mailboxes that are available on the user's home server do not
need to be available on the remote server. In addition, there may be
additional mailboxes available on the remote server, but they will
not accessible to the client via referrals unless they appear in the
LIST response to the RLIST command against the user's home server.
A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB
commands in lieu of LIST and LSUB. The RLIST and RLSUB commands
behave identically to their LIST and LSUB counterparts, except remote
mailboxes are returned in addition to local mailboxes in the LIST and
LSUB responses. This avoids displaying to a non MAILBOX-REFERRALS
enabled client inaccessible remote mailboxes.
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 indicate to the client that the mailbox is
hosted on a remote server.
When a client processes an IMAP mailbox referral, it will open a new
connection or use an existing connection to the remote server so that
it is able to issue the commands necessary to process 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 wishes to direct the client to issue
the CREATE against another server. The server can employ any means,
such as examining the hierarchy of the specified mailbox name, in
determining which server the mailbox should be created on.
Example:
C: A001 CREATE "SHARED/FOO"
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
Mailbox should be created on remote server
Alternatively, because a home server is required to maintain a
listing of referred remote mailboxes, a server MAY allow the creation
of a mailbox that will ultimately reside on a remote server against
the home server, and provide referrals on subsequent commands that
manipulate the 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 of IMAP mailbox
referrals, the first one is an URL to the existing mailbox name and
the second is an URL to the requested new mailbox name.
If within an IMAP mailbox referral pair, the existing and new mailbox
URLs are on different servers, the remote servers are unable to
perform the RENAME operation. To achieve the same behavior of
server RENAME, the client MAY issue the constituent CREATE, FETCH,
APPEND, and DELETE commands against both servers.
If within an IMAP mailbox referral pair, the existing and new mailbox
URLs are on the same server it is an indication that the currently
connected server is unable to perform the operation. The client can
simply 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 be required to make a connection to both servers and
issue the constituent commands require to achieve the RENAME.
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 make a connection 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 indicates that the destination mailbox is on
a remote server. To achieve the same behavior of 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
Arguments: reference name
mailbox name with possible wildcards
Responses: untagged responses: LIST
Result: OK - RLIST Completed
NO - RLIST Failure
BAD - command unknown or arguments invalid
The RLIST command behaves identically to its LIST counterpart, except
remote mailboxes are returned in addition to local mailboxes in the
LIST responses.
5.2 RLSUB Command
Arguments: reference name
mailbox name with possible wildcards
Responses: untagged responses: LSUB
Result: OK - RLSUB Completed
NO - RLSUB Failure
BAD - command unknown or arguments invalid
The RLSUB command behaves identically to its LSUB counterpart, except
remote mailboxes are returned in addition to local mailboxes in the
LSUB responses.
6. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) as described in [ABNF].
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
6. Security Considerations
The IMAP4 referral mechanism makes use of IMAP URLs, and as such,
have 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.
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
Many valuable suggestions were received from private discussions and
the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin,
Mark Keasling, Chris Newman and Larry Osterman 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
AI ELI5
On this page
§1Why Mailbox Referrals
With many users, many messages and geographically dispersed IMAP4 servers, it is often desirable to distribute messages among different servers within an organization. An administrator might keep personal mailboxes on a local server and shared mailboxes on a remote one, for example when bandwidth or disk resources make central storage uneconomical.
Mailbox referrals let clients reach such mailboxes seamlessly. The alternative is a proxy method, in which the local server contacts the remote server for the client and relays the data. A referral gives the client a direct connection, which is often a more efficient use of bandwidth and does not require the local server to impersonate the client when authenticating to the remote server.
Instead of a helper carrying every box between buildings, you are told where to go and fetch it yourself. That is faster for everyone.
§2Terms Used
The RFC defines a few terms. A home server is an IMAP4 server that contains the user's inbox. A remote mailbox is a mailbox not hosted on the home server, and a remote server holds remote mailboxes. A shared mailbox is one that multiple users can access. An IMAP mailbox referral is when the server directs the client to another IMAP mailbox.
Examples use C: and S: for client and server lines. The key words MUST, SHOULD and MAY follow RFC 2119 (RFC 2119).
Your home server is the place where your mail inbox lives. Any other server that holds some of your boxes is a remote one.
§3How a Referral Works
A server that supports the extension MUST list the keyword MAILBOX-REFERRALS in its CAPABILITY response. The client needs to do nothing to turn it on, and the server MUST NOT return referrals that result in a loop.
A referral is a tagged NO response with a REFERRAL response code. The code carries one or more URLs separated by spaces, as defined in RFC 1738. Multiple URLs for one object MUST all be of the same type, and for this purpose they are IMAP URLs from RFC 2192. A client MUST be prepared for a URL of any type but needs to process only IMAP URLs.
A server MAY give several referrals if there are several replicas of the mailbox, which allows load balancing or failover. How replicas are kept in sync is not covered. The preferred URL SHOULD be first, with the rest in descending order of preference. Clients may face synchronization issues if the UIDVALIDITY of the referred mailboxes differs.
Example: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox. The user;AUTH=* form is required by RFC 2192 to avoid a client falling back to anonymous login.
The server says no, but adds a note with one or more addresses of where the box really is. If there are copies, the best address comes first.
§4Referrals for Each Command
A server MAY answer SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND with one or more referrals. The client then opens a new connection, or reuses an existing one, to the remote server and issues the commands there. In the RFC's examples the client authenticates again on the second connection, then closes it with LOGOUT and continues with its first connection.
For CREATE, the server MAY refer the client to another server, choosing by any means such as the mailbox name hierarchy. Alternatively, because the home server must keep a list of referred remote mailboxes, it MAY accept the CREATE and answer with referrals on later commands.
For RENAME, the server MAY return pairs of referrals: the existing mailbox and the requested new name. If the two are on different servers, they cannot perform the rename, and the client MAY use CREATE, FETCH, APPEND and DELETE on both servers. If both are on the same server, the client can simply reissue RENAME there.
For COPY, a referral means the destination mailbox is remote. The client MAY use FETCH and APPEND against both servers to get the same result.
Most things you do to a box can send you to another computer. For moving a box between two computers, your email program has to fetch the mail from one and store it on the other.
- A001 DELETE "SHARED/FOO"
- A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]Remote mailbox. Try SERVER2.
- B001 AUTHENTICATE KERBEROS_V4Second connection.
- B001 OK user is authenticated
- B002 DELETE "SHARED/FOO"
- B002 OK DELETE completed
§5RLIST and RLSUB
Remote mailboxes reachable only by referral SHOULD NOT appear in LIST and LSUB responses from the home server. They MUST appear in RLIST and RLSUB responses. A referral-capable client issues RLIST and RLSUB in place of LIST and LSUB, which avoids showing inaccessible remote mailboxes to clients that do not support referrals.
Both commands take a reference name and a mailbox name with possible wildcards. They behave like LIST and LSUB, except that remote mailboxes are returned along with local ones. The results are OK, NO or BAD, and the untagged responses are LIST and LSUB. Hierarchy referrals, where a client must connect to the remote server to list the children of a mailbox, are not addressed.
Mailboxes on the home server need not exist on the remote server. Extra mailboxes on the remote server are not reachable by referral unless the RLIST against the home server lists them.
Referral-aware programs ask for the long list, which includes boxes kept elsewhere. Older programs get the short list so they never see boxes they cannot open.
§6Formal Syntax
The syntax uses ABNF. A mailbox_referral is a tag, a space, NO, a referral response code, and then text. The referral_response_code is [, REFERRAL and one or more space-prefixed URLs, then ]. The commands rlist and rlsub are the command name followed by a mailbox and a list_mailbox, both as defined in RFC 2060 (RFC 2060).
The grammar is a strict recipe: the word REFERRAL, then addresses in square brackets, so programs can read it without guessing.
§7Security Considerations
Referrals use IMAP URLs, so they carry the same security considerations as general URLs (RFC 1738) and IMAP URLs (RFC 2192).
With this capability it is potentially easier to write a rogue server that injects a bogus referral and sends a user to the wrong mailbox. The RFC notes that although referrals lower the effort needed to write such a server, the referral response also makes the intrusion easier to detect.
A fake server could send you to the wrong place. But because it has to say so openly, it is also easier to catch.