< draft-leiba-imap-implement-guide-03.txt   draft-leiba-imap-implement-guide-04.txt >
Network Working Group B. Leiba Network Working Group B. Leiba
Internet Draft IBM T.J. Watson Research Center Internet Draft IBM T.J. Watson Research Center
Document: draft-leiba-imap-implement-guide-03.txt October 1997 Document: draft-leiba-imap-implement-guide-04.txt November 1997
Expires March 1998 Expires April 1998
IMAP4 Implementation Recommendations IMAP4 Implementation Recommendations
Status of this Document Status of this Document
This document provides information for the Internet community. This This document provides information for the Internet community. This
document does not specify an Internet standard of any kind. document does not specify an Internet standard of any kind.
Distribution of this document is unlimited. Distribution of this document is unlimited.
This document is an Internet Draft. Internet Drafts are working This document is an Internet Draft. Internet Drafts are working
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Drafts as reference material or to cite them other than as a "working Drafts as reference material or to cite them other than as a "working
draft" or "work in progress". draft" or "work in progress".
To learn the current status of any Internet-Draft, please check the To learn the current status of any Internet-Draft, please check the
1id-abstracts.txt listing contained in the Internet-Drafts Shadow 1id-abstracts.txt listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or
munnari.oz.au. munnari.oz.au.
A revised version of this draft document will be submitted to the RFC A revised version of this draft document will be submitted to the RFC
editor. Discussion and suggestions for improvement are requested. editor. Discussion and suggestions for improvement are requested.
This document will expire by the end of March 1998. This document will expire by the end of April 1998.
1. Abstract 1. Abstract
The IMAP4 specification [RFC-2060] describes a rich protocol for use The IMAP4 specification [RFC-2060] describes a rich protocol for use
in building clients and servers for storage, retrieval, and in building clients and servers for storage, retrieval, and
manipulation of electronic mail. Because the protocol is so rich and manipulation of electronic mail. Because the protocol is so rich and
has so many implementation choices, there are often trade-offs that has so many implementation choices, there are often trade-offs that
must be made and issues that must be considered when designing such must be made and issues that must be considered when designing such
clients and servers. This document attempts to outline these issues clients and servers. This document attempts to outline these issues
and to make recommendations in order to make the end products as and to make recommendations in order to make the end products as
interoperable as possible. interoperable as possible.
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
2. Conventions used in this document 2. Conventions used in this document
In examples, "C:" indicates lines sent by a client that is connected 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. to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC-2119]. document are to be interpreted as described in [RFC-2119].
skipping to change at page 3, line 5 skipping to change at page 3, line 5
and and
4. you must avoid using the STATUS command on a mailbox that you 4. you must avoid using the STATUS command on a mailbox that you
have selected (with some server implementations the STATUS have selected (with some server implementations the STATUS
command has the same problems with multiple access as do the command has the same problems with multiple access as do the
SELECT and EXAMINE commands). SELECT and EXAMINE commands).
A further note about STATUS: The STATUS command is sometimes used to A further note about STATUS: The STATUS command is sometimes used to
check a non-selected mailbox for new mail. This mechanism MUST NOT check a non-selected mailbox for new mail. This mechanism MUST NOT
be used to check for new mail in the selected mailbox; section 5.2 of be used to check for new mail in the selected mailbox; section 5.2 of
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
[RFC-2060] specifically forbids this in its last paragraph. Further, [RFC-2060] specifically forbids this in its last paragraph. Further,
since STATUS takes a mailbox name it is an independent operation, not since STATUS takes a mailbox name it is an independent operation, not
operating on the selected mailbox. Because of this, the information operating on the selected mailbox. Because of this, the information
it returns is not necessarily in synchronization with the selected it returns is not necessarily in synchronization with the selected
mailbox state. mailbox state.
3.1.2. Severed Connections 3.1.2. Severed Connections
The client/server connection may be severed for one of three reasons: The client/server connection may be severed for one of three reasons:
skipping to change at page 4, line 5 skipping to change at page 4, line 5
When the server wants to sever a connection it's usually due to an When the server wants to sever a connection it's usually due to an
inactivity timeout or is because a situation has arisen that has inactivity timeout or is because a situation has arisen that has
changed the state of the mail store in a way that the server can not changed the state of the mail store in a way that the server can not
communicate to the client. The server SHOULD send an untagged BYE communicate to the client. The server SHOULD send an untagged BYE
response to the client and then close the socket. Sending an response to the client and then close the socket. Sending an
untagged BYE response before severing allows the server to send a untagged BYE response before severing allows the server to send a
human-readable explanation of the problem to the client, which the human-readable explanation of the problem to the client, which the
client may then log, display to the user, or both (see section 7.1.5 client may then log, display to the user, or both (see section 7.1.5
of [RFC-2060]). of [RFC-2060]).
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
3.2. Scaling 3.2. Scaling
IMAP4 has many features that allow for scalability, as mail stores IMAP4 has many features that allow for scalability, as mail stores
become larger and more numerous. Large numbers of users, mailboxes, become larger and more numerous. Large numbers of users, mailboxes,
and messages, and very large messages require thought to handle and messages, and very large messages require thought to handle
efficiently. This document will not address the administrative efficiently. This document will not address the administrative
issues involved in large numbers of users, but we will look at the issues involved in large numbers of users, but we will look at the
other items. other items.
skipping to change at page 5, line 5 skipping to change at page 5, line 5
to determine the mailbox list. Because of this, clients SHOULD NOT to determine the mailbox list. Because of this, clients SHOULD NOT
use an unqualified "*" that way in the LIST command. A safer use an unqualified "*" that way in the LIST command. A safer
approach is to list each level of hierarchy individually, allowing approach is to list each level of hierarchy individually, allowing
the user to traverse the tree one limb at a time, thus: the user to traverse the tree one limb at a time, thus:
C: 001 LIST "" % C: 001 LIST "" %
S: * LIST () "/" Banana S: * LIST () "/" Banana
S: * LIST ...etc... S: * LIST ...etc...
S: 001 OK done S: 001 OK done
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
and then and then
C: 002 LIST "" Banana/% C: 002 LIST "" Banana/%
S: * LIST () "/" Banana/Apple S: * LIST () "/" Banana/Apple
S: * LIST ...etc... S: * LIST ...etc...
S: 002 OK done S: 002 OK done
Using this technique the client's user interface can give the user Using this technique the client's user interface can give the user
full flexibility without choking on the voluminous reply to "LIST *". full flexibility without choking on the voluminous reply to "LIST *".
Of course, it is still possible that the reply to Of course, it is still possible that the reply to
skipping to change at page 6, line 5 skipping to change at page 6, line 5
server blocked by a storm of FETCH replies. (Such a method could be server blocked by a storm of FETCH replies. (Such a method could be
reversed to fetch the LAST 50 messages first, then the 50 prior to reversed to fetch the LAST 50 messages first, then the 50 prior to
that, and so on.) that, and so on.)
As a smart extension of this, a well designed client, prepared for As a smart extension of this, a well designed client, prepared for
very large mailboxes, will not automatically fetch data for all very large mailboxes, will not automatically fetch data for all
messages AT ALL. Rather, the client will populate the user's view messages AT ALL. Rather, the client will populate the user's view
only as the user sees it, possibly pre-fetching selected information, only as the user sees it, possibly pre-fetching selected information,
and only fetching other information as the user scrolls to it. For and only fetching other information as the user scrolls to it. For
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
example, to select only those messages beginning with the first example, to select only those messages beginning with the first
unseen one: unseen one:
C: 003 SELECT INBOX C: 003 SELECT INBOX
S: * 10000 EXISTS S: * 10000 EXISTS
S: * 80 RECENT S: * 80 RECENT
S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen) S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen)
S: * OK [UIDVALIDITY 824708485] UID validity status S: * OK [UIDVALIDITY 824708485] UID validity status
S: * OK [UNSEEN 9921] First unseen message S: * OK [UNSEEN 9921] First unseen message
skipping to change at page 7, line 5 skipping to change at page 7, line 5
S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000}
S: ...data...) S: ...data...)
S: 022 OK done S: 022 OK done
C: 023 FETCH 3 BODY[1]<20001.20000> C: 023 FETCH 3 BODY[1]<20001.20000>
S: * 3 FETCH (BODY[1]<20001> {20000} S: * 3 FETCH (BODY[1]<20001> {20000}
S: ...data...) S: ...data...)
S: 023 OK done S: 023 OK done
C: 024 FETCH 3 BODY[1]<40001.20000> C: 024 FETCH 3 BODY[1]<40001.20000>
...etc... ...etc...
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
3.2.1.4. BODYSTRUCTURE vs. Entire Messages 3.2.1.4. BODYSTRUCTURE vs. Entire Messages
Because FETCH BODYSTRUCTURE is necessary in order to determine the Because FETCH BODYSTRUCTURE is necessary in order to determine the
number of body parts, and, thus, whether a message has "attachments", number of body parts, and, thus, whether a message has "attachments",
clients often use FETCH FULL as their normal method of populating the clients often use FETCH FULL as their normal method of populating the
user's view of a mailbox. The benefit is that the client can display user's view of a mailbox. The benefit is that the client can display
a paperclip icon or some such indication along with the normal a paperclip icon or some such indication along with the normal
message summary. However, this comes at a significant cost with some message summary. However, this comes at a significant cost with some
server configurations. The parsing needed to generate the FETCH server configurations. The parsing needed to generate the FETCH
skipping to change at page 8, line 5 skipping to change at page 8, line 5
49,000 octets long, and, clearly, one can construct a command line 49,000 octets long, and, clearly, one can construct a command line
that's even longer. that's even longer.
A client SHOULD limit the length of the command lines it generates to A client SHOULD limit the length of the command lines it generates to
approximately 1000 octets (including all quoted strings but not approximately 1000 octets (including all quoted strings but not
including literals). If the client is unable to group things into including literals). If the client is unable to group things into
ranges so that the command line is within that length, it SHOULD ranges so that the command line is within that length, it SHOULD
split the request into multiple commands. The client SHOULD use split the request into multiple commands. The client SHOULD use
literals instead of long quoted strings, in order to keep the command literals instead of long quoted strings, in order to keep the command
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
length down. length down.
For its part, a server SHOULD allow for a command line of at least For its part, a server SHOULD allow for a command line of at least
8000 octets. This provides plenty of leeway for accepting reasonable 8000 octets. This provides plenty of leeway for accepting reasonable
length commands from clients. The server SHOULD send a BAD response length commands from clients. The server SHOULD send a BAD response
to a command that does not end within the server's maximum accepted to a command that does not end within the server's maximum accepted
command length. command length.
3.2.2. Subscriptions 3.2.2. Subscriptions
skipping to change at page 9, line 5 skipping to change at page 9, line 5
that the search is being done (and is probably aware that it might be that the search is being done (and is probably aware that it might be
time-consuming). time-consuming).
The client MAY allow other commands to be sent to the server while a The client MAY allow other commands to be sent to the server while a
SEARCH is in progress, but at the time of this writing there is SEARCH is in progress, but at the time of this writing there is
little or no server support for parallel processing of multiple little or no server support for parallel processing of multiple
commands in the same session (and see "Multiple Accesses of the Same commands in the same session (and see "Multiple Accesses of the Same
Mailbox" above for a description of the dangers of trying to work Mailbox" above for a description of the dangers of trying to work
around this by doing your SEARCH in another session). around this by doing your SEARCH in another session).
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
Another word about text searches: some servers, built on database Another word about text searches: some servers, built on database
back-ends with indexed search capabilities, may return search results back-ends with indexed search capabilities, may return search results
that do not match the IMAP spec's "case-insensitive substring" that do not match the IMAP spec's "case-insensitive substring"
requirements. While these servers are in violation of the protocol, requirements. While these servers are in violation of the protocol,
there is little harm in the violation as long as the search results there is little harm in the violation as long as the search results
are used only to response to a user's request. Still, developers of are used only to response to a user's request. Still, developers of
such servers should be aware that they ARE violating the protocol, such servers should be aware that they ARE violating the protocol,
should think carefully about that behaviour, and MUST be certain that should think carefully about that behaviour, and MUST be certain that
their servers respond accurately to the flag searches for the reasons their servers respond accurately to the flag searches for the reasons
skipping to change at page 10, line 5 skipping to change at page 10, line 5
advantage of them SHOULD use the CAPABILITY response to determine advantage of them SHOULD use the CAPABILITY response to determine
whether they may be used or not. whether they may be used or not.
3.3.2. Don't Do What the Server Says You Can't 3.3.2. Don't Do What the Server Says You Can't
In many cases, the server, in response to a command, will tell the In many cases, the server, in response to a command, will tell the
client something about what can and can't be done with a particular client something about what can and can't be done with a particular
mailbox. The client SHOULD pay attention to this information and mailbox. The client SHOULD pay attention to this information and
SHOULD NOT try to do things that it's been told it can't do. SHOULD NOT try to do things that it's been told it can't do.
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
Examples: Examples:
* Do not try to SELECT a mailbox that has the \Noselect flag set. * Do not try to SELECT a mailbox that has the \Noselect flag set.
* Do not try to CREATE a sub-mailbox in a mailbox that has the * Do not try to CREATE a sub-mailbox in a mailbox that has the
\Noinferiors flag set. \Noinferiors flag set.
* Do not respond to a failing COPY or APPEND command by trying to * Do not respond to a failing COPY or APPEND command by trying to
CREATE the target mailbox if the server does not respond with a CREATE the target mailbox if the server does not respond with a
[TRYCREATE] response code. [TRYCREATE] response code.
* Do not try to expunge a mailbox that has been selected with the * Do not try to expunge a mailbox that has been selected with the
[READ-ONLY] response code. [READ-ONLY] response code.
skipping to change at page 11, line 5 skipping to change at page 11, line 5
string for this field. string for this field.
3.4.2. Special Characters 3.4.2. Special Characters
Certain characters, currently the double-quote and the backslash, may Certain characters, currently the double-quote and the backslash, may
not be sent as-is inside a quoted string. These characters MUST be not be sent as-is inside a quoted string. These characters MUST be
preceded by the escape character if they are in a quoted string, or preceded by the escape character if they are in a quoted string, or
else the string must be sent as a literal. Both clients and servers else the string must be sent as a literal. Both clients and servers
MUST handle this, both on output (they must send these characters MUST handle this, both on output (they must send these characters
Internet DRAFT Implementation Recommendations September 1997 Internet DRAFT Implementation Recommendations November 1997
properly) and on input (they must be able to receive escaped properly) and on input (they must be able to receive escaped
characters in quoted strings). Example: characters in quoted strings). Example:
C: 001 LIST "" % C: 001 LIST "" %
S: * LIST () "" INBOX S: * LIST () "" INBOX
S: * LIST () "\\" TEST S: * LIST () "\\" TEST
S: * LIST () "\\" {12} S: * LIST () "\\" {12}
S: "My" mailbox S: "My" mailbox
S: 001 OK done S: 001 OK done
skipping to change at page 11, line 30 skipping to change at page 11, line 30
Note that in the example the server sent the hierarchy delimiter as Note that in the example the server sent the hierarchy delimiter as
an escaped character in the quoted string and sent the mailbox name an escaped character in the quoted string and sent the mailbox name
containing imbedded double-quotes as a literal. The client used only containing imbedded double-quotes as a literal. The client used only
quoted strings, escaping both the backslash and the double-quote quoted strings, escaping both the backslash and the double-quote
characters. characters.
The CR and LF characters may be sent ONLY in literals; they are not The CR and LF characters may be sent ONLY in literals; they are not
allowed, even if escaped, inside quoted strings. allowed, even if escaped, inside quoted strings.
And while we're talking about special characters: the IMAP spec, in
the section titled "Mailbox International Naming Convention",
describes how to encode mailbox names in modified UTF-7.
Implementations MUST adhere to this in order to be interoperable in
the international market, and servers SHOULD validate mailbox names
sent by client and reject names that do not conform.
3.4.3. UIDs and UIDVALIDITY 3.4.3. UIDs and UIDVALIDITY
Servers that support existing back-end mail stores often have no good Servers that support existing back-end mail stores often have no good
place to save UIDs for messages. Often the existing mail store will place to save UIDs for messages. Often the existing mail store will
not have the concept of UIDs in the sense that IMAP has: strictly not have the concept of UIDs in the sense that IMAP has: strictly
increasing, never re-issued, 32-bit integers. Some servers solve increasing, never re-issued, 32-bit integers. Some servers solve
this by storing the UIDs in a place that's accessible to end users, this by storing the UIDs in a place that's accessible to end users,
allowing for the possibility that the users will delete them. Others allowing for the possibility that the users will delete them. Others
solve it by re-assigning UIDs every time a mailbox is selected. solve it by re-assigning UIDs every time a mailbox is selected.
The server SHOULD maintain UIDs permanently for all messages if it The server SHOULD maintain UIDs permanently for all messages if it
can. If that's not possible, the server MUST change the UIDVALIDITY can. If that's not possible, the server MUST change the UIDVALIDITY
value for the mailbox whenever any of the UIDs may have become value for the mailbox whenever any of the UIDs may have become
invalid. Clients MUST recognize that the UIDVALIDITY has changed and invalid. Clients MUST recognize that the UIDVALIDITY has changed and
MUST respond to that condition by throwing away any information that MUST respond to that condition by throwing away any information that
they have saved about UIDs in that mailbox. There have been many they have saved about UIDs in that mailbox. There have been many
problems in this area when clients have failed to do this; in the problems in this area when clients have failed to do this; in the
worst case it will result in loss of mail when a client deletes the worst case it will result in loss of mail when a client deletes the
Internet DRAFT Implementation Recommendations November 1997
wrong piece of mail by using a stale UID. wrong piece of mail by using a stale UID.
It seems to be a common myth that "the UIDVALIDITY and the UID, taken It seems to be a common myth that "the UIDVALIDITY and the UID, taken
together, form a 64-bit identifier that uniquely identifies a message together, form a 64-bit identifier that uniquely identifies a message
on a server". This is absolutely NOT TRUE. There is no assurance on a server". This is absolutely NOT TRUE. There is no assurance
that the UIDVALIDITY values of two mailboxes be different, so the that the UIDVALIDITY values of two mailboxes be different, so the
UIDVALIDITY in no way identifies a mailbox. The ONLY purpose of UIDVALIDITY in no way identifies a mailbox. The ONLY purpose of
Internet DRAFT Implementation Recommendations September 1997
UIDVALIDITY is, as its name indicates, to give the client a way to UIDVALIDITY is, as its name indicates, to give the client a way to
check the validity of the UIDs it has cached. While it is a valid check the validity of the UIDs it has cached. While it is a valid
implementation choice to put these values together to make a 64-bit implementation choice to put these values together to make a 64-bit
identifier for the message, the important concept here is that UIDs identifier for the message, the important concept here is that UIDs
are not unique between mailboxes; they are only unique WITHIN a given are not unique between mailboxes; they are only unique WITHIN a given
mailbox. mailbox.
Some server implementations have toyed with making UIDs unique across Some server implementations have toyed with making UIDs unique across
the entire server. This is inadvisable, in that it limits the life the entire server. This is inadvisable, in that it limits the life
of UIDs unnecessarily. The UID is a 32-bit number and will run out of UIDs unnecessarily. The UID is a 32-bit number and will run out
skipping to change at page 12, line 46 skipping to change at page 13, line 5
Under extreme circumstances (and this is extreme, indeed), the server Under extreme circumstances (and this is extreme, indeed), the server
may have to invalidate UIDs while a mailbox is in use by a client - may have to invalidate UIDs while a mailbox is in use by a client -
that is, the UIDs that the client knows about in its active mailbox that is, the UIDs that the client knows about in its active mailbox
are no longer valid. In that case, the server MUST immediately are no longer valid. In that case, the server MUST immediately
change the UIDVALIDITY and MUST communicate this to the client. The change the UIDVALIDITY and MUST communicate this to the client. The
server MAY do this by sending an unsolicited UIDVALIDITY message, in server MAY do this by sending an unsolicited UIDVALIDITY message, in
the same form as in response to the SELECT command. Clients MUST be the same form as in response to the SELECT command. Clients MUST be
prepared to handle such a message and the possibly coincident failure prepared to handle such a message and the possibly coincident failure
of the command in process. For example: of the command in process. For example:
Internet DRAFT Implementation Recommendations November 1997
C: 032 UID STORE 382 +Flags.silent \Deleted C: 032 UID STORE 382 +Flags.silent \Deleted
S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value!
S: 032 NO UID command rejeced because UIDVALIDITY changed! S: 032 NO UID command rejeced because UIDVALIDITY changed!
C: ...invalidates local information and re-fetches... C: ...invalidates local information and re-fetches...
C: 033 FETCH 1:* UID C: 033 FETCH 1:* UID
...etc... ...etc...
At the time of the writing of this document, the only server known to At the time of the writing of this document, the only server known to
do this does so only under the following condition: the client do this does so only under the following condition: the client
selects INBOX, but there is not yet a physical INBOX file created. selects INBOX, but there is not yet a physical INBOX file created.
Internet DRAFT Implementation Recommendations September 1997
Nonetheless, the SELECT succeeds, exporting an empty INBOX with a Nonetheless, the SELECT succeeds, exporting an empty INBOX with a
temporary UIDVALIDITY of 1. While the INBOX remains selected, mail temporary UIDVALIDITY of 1. While the INBOX remains selected, mail
is delivered to the user, which creates the real INBOX file and is delivered to the user, which creates the real INBOX file and
assigns a permanent UIDVALIDITY (that is likely not to be 1). The assigns a permanent UIDVALIDITY (that is likely not to be 1). The
server reports the change of UIDVALIDITY, but as there were no server reports the change of UIDVALIDITY, but as there were no
messages before, so no UIDs have actually changed, all the client messages before, so no UIDs have actually changed, all the client
must do is accept the change in UIDVALIDITY. must do is accept the change in UIDVALIDITY.
Alternatively, a server may force the client to re-select the Alternatively, a server may force the client to re-select the
mailbox, at which time it will obtain a new UIDVALIDITY value. To do mailbox, at which time it will obtain a new UIDVALIDITY value. To do
skipping to change at page 13, line 43 skipping to change at page 14, line 5
examples: examples:
C: 001 FETCH 1 UID FLAGS INTERNALDATE C: 001 FETCH 1 UID FLAGS INTERNALDATE
S: * 5 FETCH (FLAGS (\Deleted)) S: * 5 FETCH (FLAGS (\Deleted))
S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345)
S: 001 OK done S: 001 OK done
(In this case, the responses are in a different order. Also, the (In this case, the responses are in a different order. Also, the
server returned a flag update for message 5, which wasn't part of the server returned a flag update for message 5, which wasn't part of the
client's request.) client's request.)
Internet DRAFT Implementation Recommendations November 1997
C: 002 FETCH 2 UID FLAGS INTERNALDATE C: 002 FETCH 2 UID FLAGS INTERNALDATE
S: * 2 FETCH (INTERNALDATE "...") S: * 2 FETCH (INTERNALDATE "...")
S: * 2 FETCH (UID 399) S: * 2 FETCH (UID 399)
S: * 2 FETCH (FLAGS ()) S: * 2 FETCH (FLAGS ())
S: 002 OK done S: 002 OK done
(In this case, the responses are in a different order and were (In this case, the responses are in a different order and were
returned in separate responses.) returned in separate responses.)
Internet DRAFT Implementation Recommendations September 1997
C: 003 FETCH 2 BODY[1] C: 003 FETCH 2 BODY[1]
S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14}
S: Hello world! S: Hello world!
S: ) S: )
S: 003 OK done S: 003 OK done
(In this case, the FLAGS response was added by the server, since (In this case, the FLAGS response was added by the server, since
fetching the body part caused the server to set the \Seen flag.) fetching the body part caused the server to set the \Seen flag.)
Because of this characteristic a client MUST be ready to receive any Because of this characteristic a client MUST be ready to receive any
FETCH response at any time and should use that information to update FETCH response at any time and should use that information to update
skipping to change at page 14, line 47 skipping to change at page 15, line 4
When this is the case, some servers have chosen to estimate the size, When this is the case, some servers have chosen to estimate the size,
rather than to compute it precisely. Such an estimate allows the rather than to compute it precisely. Such an estimate allows the
client to display an approximate size to the user and to use the client to display an approximate size to the user and to use the
estimate in flood control considerations (q.v.), but requires that estimate in flood control considerations (q.v.), but requires that
the client not use the size for things such as allocation of buffers, the client not use the size for things such as allocation of buffers,
because those buffers might then be too small to hold the actual MIME because those buffers might then be too small to hold the actual MIME
stream. Instead, a client SHOULD use the size that's returned in the stream. Instead, a client SHOULD use the size that's returned in the
literal when you fetch the data. literal when you fetch the data.
The protocol requires that the RFC822.SIZE value returned by the The protocol requires that the RFC822.SIZE value returned by the
Internet DRAFT Implementation Recommendations November 1997
server be EXACT. Estimating the size is a protocol violation, and server be EXACT. Estimating the size is a protocol violation, and
server designers must be aware that, despite the performance savings server designers must be aware that, despite the performance savings
they might realize in using an estimate, this practice will cause they might realize in using an estimate, this practice will cause
some clients to fail in various ways. If possible, the server SHOULD some clients to fail in various ways. If possible, the server SHOULD
compute the RFC822.SIZE for a particular message once, and then save compute the RFC822.SIZE for a particular message once, and then save
it for later retrieval. If that's not possible, the server MUST it for later retrieval. If that's not possible, the server MUST
compute the value exactly every time. Incorrect estimates do cause compute the value exactly every time. Incorrect estimates do cause
severe interoperability problems with some clients. severe interoperability problems with some clients.
Internet DRAFT Implementation Recommendations September 1997
3.4.6. Expunged Messages 3.4.6. Expunged Messages
If the server allows multiple connections to the same mailbox, it is If the server allows multiple connections to the same mailbox, it is
often possible for messages to be expunged in one client unbeknownst often possible for messages to be expunged in one client unbeknownst
to another client. Since the server is not allowed to tell the to another client. Since the server is not allowed to tell the
client about these expunged messages in response to a FETCH command, client about these expunged messages in response to a FETCH command,
the server may have to deal with the issue of how to return the server may have to deal with the issue of how to return
information about an expunged message. There was extensive information about an expunged message. There was extensive
discussion about this issue, and the results of that discussion are discussion about this issue, and the results of that discussion are
summarized in [RFC-2180]. See that reference for a detailed summarized in [RFC-2180]. See that reference for a detailed
skipping to change at page 15, line 44 skipping to change at page 16, line 4
(See also "Reference Names in the LIST Command" below.) (See also "Reference Names in the LIST Command" below.)
3.4.8. Creating Special-Use Mailboxes 3.4.8. Creating Special-Use Mailboxes
It may seem at first that this is part of the namespace issue; it is It may seem at first that this is part of the namespace issue; it is
not, and is only indirectly related to it. A number of clients like not, and is only indirectly related to it. A number of clients like
to create special-use mailboxes with particular names. Most to create special-use mailboxes with particular names. Most
commonly, clients with a "trash folder" model of message deletion commonly, clients with a "trash folder" model of message deletion
want to create a mailbox with the name "Trash" or "Deleted". Some want to create a mailbox with the name "Trash" or "Deleted". Some
clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a
Internet DRAFT Implementation Recommendations November 1997
"Sent Mail" mailbox. And so on. There are two major "Sent Mail" mailbox. And so on. There are two major
interoperability problems with this practice: interoperability problems with this practice:
1. different clients may use different names for mailboxes with 1. different clients may use different names for mailboxes with
similar functions (such as "Trash" and "Deleted"), or may manage the similar functions (such as "Trash" and "Deleted"), or may manage the
same mailboxes in different ways, causing problems if a user switches same mailboxes in different ways, causing problems if a user switches
between clients and between clients and
2. there is no guarantee that the server will allow the creation of 2. there is no guarantee that the server will allow the creation of
the desired mailbox. the desired mailbox.
Internet DRAFT Implementation Recommendations September 1997
The client developer is, therefore, well advised to consider The client developer is, therefore, well advised to consider
carefully the creation of any special-use mailboxes on the server, carefully the creation of any special-use mailboxes on the server,
and, further, the client MUST NOT require such mailbox creation - and, further, the client MUST NOT require such mailbox creation -
that is, if you do decide to do this, you MUST handle gracefully the that is, if you do decide to do this, you MUST handle gracefully the
failure of the CREATE command and behave reasonably when your failure of the CREATE command and behave reasonably when your
special-use mailboxes do not exist and can not be created. special-use mailboxes do not exist and can not be created.
In addition, the client developer SHOULD provide a convenient way for In addition, the client developer SHOULD provide a convenient way for
the user to select the names for any special-use mailboxes, allowing the user to select the names for any special-use mailboxes, allowing
the user to make these names the same in all clients s/he uses and to the user to make these names the same in all clients s/he uses and to
skipping to change at page 16, line 47 skipping to change at page 17, line 5
in those configurations. Second, while some IMAP servers expose the in those configurations. Second, while some IMAP servers expose the
underlying file system to the clients, others allow access only to underlying file system to the clients, others allow access only to
the user's personal mailboxes, or to some other limited set of files, the user's personal mailboxes, or to some other limited set of files,
making such file-system-like semantics less meaningful. Third, making such file-system-like semantics less meaningful. Third,
because the IMAP spec leaves the interpretation of the reference name because the IMAP spec leaves the interpretation of the reference name
as "implementation-dependent", the various server implementations as "implementation-dependent", the various server implementations
handle it in vastly differing ways, and fourth, many implementers handle it in vastly differing ways, and fourth, many implementers
simply do not understand it and misuse it, do not use it, or ignore simply do not understand it and misuse it, do not use it, or ignore
it as a result. it as a result.
Internet DRAFT Implementation Recommendations November 1997
The following statement gets somewhat into the religious issues that The following statement gets somewhat into the religious issues that
we've tried to avoid scrupulously here; so be it: because of the we've tried to avoid scrupulously here; so be it: because of the
confusion around the reference name, its use by a client is a confusion around the reference name, its use by a client is a
dangerous thing, prone to result in interoperability problems. There dangerous thing, prone to result in interoperability problems. There
are servers that interpret it as originally intended; there are are servers that interpret it as originally intended; there are
servers that ignore it completely; there are servers that simply servers that ignore it completely; there are servers that simply
prepend it to the mailbox name (with or without inserting a hierarchy prepend it to the mailbox name (with or without inserting a hierarchy
Internet DRAFT Implementation Recommendations September 1997
delimiter in between). Because a client can't know which of these delimiter in between). Because a client can't know which of these
four behaviours to expect, a client SHOULD NOT use a reference name four behaviours to expect, a client SHOULD NOT use a reference name
itself, expecting a particular server behavior. However, a client itself, expecting a particular server behavior. However, a client
SHOULD permit a USER, by configuration, to use a reference name. SHOULD permit a USER, by configuration, to use a reference name.
There is in no way universal agreement about the use or non-use of There is in no way universal agreement about the use or non-use of
the reference name. The last words here are, "Be aware." the reference name. The last words here are, "Be aware."
3.4.10. Deleting Mailboxes 3.4.10. ALERT Response Codes
The protocol spec is very clear on the matter of what to do with
ALERT response codes, and yet there are many clients that violate it
so it needs to be said anyway: "The human-readable text contains a
special alert that MUST be presented to the user in a fashion that
calls the user's attention to the message." Enough said. Do it.
3.4.11. Deleting Mailboxes
The protocol does not guarantee that a client may delete a mailbox The protocol does not guarantee that a client may delete a mailbox
that is not empty, though on some servers it is permissible and is, that is not empty, though on some servers it is permissible and is,
in fact, much faster than the alternative or deleting all the in fact, much faster than the alternative or deleting all the
messages from the client. If the client chooses to try to take messages from the client. If the client chooses to try to take
advantage of this possibility it MUST be prepared to use the other advantage of this possibility it MUST be prepared to use the other
method in the even that the more convenient one fails. Further, a method in the even that the more convenient one fails. Further, a
client SHOULD NOT try to delete the mailbox that it has selected, but client SHOULD NOT try to delete the mailbox that it has selected, but
should first close that mailbox; some servers do not permit the should first close that mailbox; some servers do not permit the
deletion of the selected mailbox. deletion of the selected mailbox.
That said, a server SHOULD permit the deletion of a non-empty That said, a server SHOULD permit the deletion of a non-empty
mailbox; there's little reason to pass this work on to the client. mailbox; there's little reason to pass this work on to the client.
Moreover, forbidding this prevents the deletion of a mailbox that for Moreover, forbidding this prevents the deletion of a mailbox that for
some reason can not be opened or expunged, leading to possible some reason can not be opened or expunged, leading to possible
denial-of-service problems. denial-of-service problems.
Internet DRAFT Implementation Recommendations November 1997
Example: Example:
[User tells the client to delete mailbox BANANA, which is [User tells the client to delete mailbox BANANA, which is
currently selected...] currently selected...]
C: 008 CLOSE C: 008 CLOSE
S: 008 OK done S: 008 OK done
C: 009 DELETE BANANA C: 009 DELETE BANANA
S: 009 NO Delete failed; mailbox is not empty. S: 009 NO Delete failed; mailbox is not empty.
C: 010 SELECT BANANA C: 010 SELECT BANANA
S: * ... untagged SELECT responses S: * ... untagged SELECT responses
S: 010 OK done S: 010 OK done
skipping to change at page 18, line 4 skipping to change at page 18, line 28
S: 011 OK done S: 011 OK done
C: 012 CLOSE C: 012 CLOSE
S: 012 OK done S: 012 OK done
C: 013 DELETE BANANA C: 013 DELETE BANANA
S: 013 OK done S: 013 OK done
3.5. A Word About Testing 3.5. A Word About Testing
Since the whole point of IMAP is interoperability, and since Since the whole point of IMAP is interoperability, and since
interoperability can not be tested in a vacuum, the final interoperability can not be tested in a vacuum, the final
Internet DRAFT Implementation Recommendations September 1997
recommendation of this treatise is, "Test against EVERYTHING." Test recommendation of this treatise is, "Test against EVERYTHING." Test
your client against every server you can get an account on. Test your client against every server you can get an account on. Test
your server with every client you can get your hands on. Many your server with every client you can get your hands on. Many
clients make limited test versions available on the Web for the clients make limited test versions available on the Web for the
downloading. Many server owners will give serious client developers downloading. Many server owners will give serious client developers
guest accounts for testing. Contact them and ask. NEVER assume that guest accounts for testing. Contact them and ask. NEVER assume that
because your client works with one or two servers, or because your because your client works with one or two servers, or because your
server does fine with one or two clients, you will interoperate well server does fine with one or two clients, you will interoperate well
in general. in general.
skipping to change at page 18, line 31 skipping to change at page 19, line 5
See the following URLs on the web for more information here: See the following URLs on the web for more information here:
IMAP Products and Sources: http://www.imap.org/products.html IMAP Products and Sources: http://www.imap.org/products.html
IMC MailConnect: http://www.imc.org/imc-mailconnect IMC MailConnect: http://www.imc.org/imc-mailconnect
4. Security Considerations 4. Security Considerations
This document describes behaviour of clients and servers that use the This document describes behaviour of clients and servers that use the
IMAP4 protocol, and as such, has the same security considerations as IMAP4 protocol, and as such, has the same security considerations as
described in [RFC-2060]. described in [RFC-2060].
Internet DRAFT Implementation Recommendations November 1997
5. References 5. References
[RFC-2060], Crispin, M., "Internet Message Access Protocol - Version [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, University of Washington, December 1996. 4rev1", RFC 2060, University of Washington, December 1996.
[RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, Harvard University, March 1997. Requirement Levels", RFC 2119, Harvard University, March 1997.
[RFC-2180], Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC [RFC-2180], Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
2180, Microsoft, July 1997. 2180, Microsoft, July 1997.
[NAMESPACE], Gahrns, M. & Newman, C., "IMAP4 Namespace", draft [NAMESPACE], Gahrns, M. & Newman, C., "IMAP4 Namespace", draft
document <draft-gahrns-imap-namespace-01.txt>, June 1997. document <draft-gahrns-imap-namespace-01.txt>, June 1997.
6. Acknowledgments 6. Acknowledgments
This document is the result of discussions on the IMAP4 mailing list and To be completed...
is meant to reflect consensus of this group. In particular, Mark
Crispin, Steve Hole, and Portia Shao made significant comments or
suggestions during the review of this document.
Internet DRAFT Implementation Recommendations September 1997
7. Author's Address 7. Author's Address
Barry Leiba Barry Leiba
IBM T.J. Watson Research Center IBM T.J. Watson Research Center
30 Saw Mill River Road 30 Saw Mill River Road
Hawthorne, NY 10532 Hawthorne, NY 10532
Phone: 1-914-784-7941 Phone: 1-914-784-7941
Email: leiba@watson.ibm.com Email: leiba@watson.ibm.com
 End of changes. 30 change blocks. 
38 lines changed or deleted 49 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/