Crispin Standards Track [Page 28]
RFC 2060 IMAP4rev1 December 1996
C: Z432 LIST "" *
S: * LIST () "." INBOX
S: * LIST () "." INBOX.bar
S: Z432 OK LIST completed
C: Z433 RENAME INBOX old-mail
S: Z433 OK RENAME completed
C: Z434 LIST "" *
S: * LIST () "." INBOX
S: * LIST () "." INBOX.bar
S: * LIST () "." old-mail
S: Z434 OK LIST completed
6.3.6. SUBSCRIBE Command
Arguments: mailbox
Responses: no specific responses for this command
Result: OK - subscribe completed
NO - subscribe failure: can't subscribe to that name
BAD - command unknown or arguments invalid
The SUBSCRIBE command adds the specified mailbox name to the
server's set of "active" or "subscribed" mailboxes as returned by
the LSUB command. This command returns a tagged OK response only
if the subscription is successful.
A server MAY validate the mailbox argument to SUBSCRIBE to verify
that it exists. However, it MUST NOT unilaterally remove an
existing mailbox name from the subscription list even if a mailbox
by that name no longer exists.
Note: this requirement is because some server sites may routinely
remove a mailbox with a well-known name (e.g. "system-alerts")
after its contents expire, with the intention of recreating it
when new contents are appropriate.
Example: C: A002 SUBSCRIBE #news.comp.mail.mime
S: A002 OK SUBSCRIBE completed
Crispin Standards Track [Page 29]
RFC 2060 IMAP4rev1 December 1996
6.3.7. UNSUBSCRIBE Command
Arguments: mailbox name
Responses: no specific responses for this command
Result: OK - unsubscribe completed
NO - unsubscribe failure: can't unsubscribe that name
BAD - command unknown or arguments invalid
The UNSUBSCRIBE command removes the specified mailbox name from
the server's set of "active" or "subscribed" mailboxes as returned
by the LSUB command. This command returns a tagged OK response
only if the unsubscription is successful.
Example: C: A002 UNSUBSCRIBE #news.comp.mail.mime
S: A002 OK UNSUBSCRIBE completed
6.3..8. LIST Command
Arguments: reference name
mailbox name with possible wildcards
Responses: untagged responses: LIST
Result: OK - list completed
NO - list failure: can't list that reference or name
BAD - command unknown or arguments invalid
The LIST command returns a subset of names from the complete set
of all names available to the client. Zero or more untagged LIST
replies are returned, containing the name attributes, hierarchy
delimiter, and name; see the description of the LIST reply for
more detail.
The LIST command SHOULD return its data quickly, without undue
delay. For example, it SHOULD NOT go to excess trouble to
calculate \Marked or \Unmarked status or perform other processing;
if each name requires 1 second of processing, then a list of 1200
names would take 20 minutes!
An empty ("" string) reference name argument indicates that the
mailbox name is interpreted as by SELECT. The returned mailbox
names MUST match the supplied mailbox name pattern. A non-empty
reference name argument is the name of a mailbox or a level of
mailbox hierarchy, and indicates a context in which the mailbox
name is interpreted in an implementation-defined manner.
Crispin Standards Track [Page 30]
RFC 2060 IMAP4rev1 December 1996
An empty ("" string) mailbox name argument is a special request to
return the hierarchy delimiter and the root name of the name given
in the reference. The value returned as the root MAY be null if
the reference is non-rooted or is null. In all cases, the
hierarchy delimiter is returned. This permits a client to get the
hierarchy delimiter even when no mailboxes by that name currently
exist.
The reference and mailbox name arguments are interpreted, in an
implementation-dependent fashion, into a canonical form that
represents an unambiguous left-to-right hierarchy. The returned
mailbox names will be in the interpreted form.
Any part of the reference argument that is included in the
interpreted form SHOULD prefix the interpreted form. It SHOULD
also be in the same form as the reference name argument. This
rule permits the client to determine if the returned mailbox name
is in the context of the reference argument, or if something about
the mailbox argument overrode the reference argument. Without
this rule, the client would have to have knowledge of the server's
naming semantics including what characters are "breakouts" that
override a naming context.
For example, here are some examples of how references and mailbox
names might be interpreted on a UNIX-based server:
Reference Mailbox Name Interpretation
------------ ------------ --------------
~smith/Mail/ foo.* ~smith/Mail/foo.*
archive/ % archive/%
#news. comp.mail.* #news.comp.mail.*
~smith/Mail/ /usr/doc/foo /usr/doc/foo
archive/ ~fred/Mail/* ~fred/Mail/*
The first three examples demonstrate interpretations in the
context of the reference argument. Note that "~smith/Mail" SHOULD
NOT be transformed into something like "/u2/users/smith/Mail", or
it would be impossible for the client to determine that the
interpretation was in the context of the reference.
The character "*" is a wildcard, and matches zero or more
characters at this position. The character "%" is similar to "*",
but it does not match a hierarchy delimiter. If the "%" wildcard
is the last character of a mailbox name argument, matching levels
of hierarchy are also returned. If these levels of hierarchy are
not also selectable mailboxes, they are returned with the
\Noselect mailbox name attribute (see the description of the LIST
response for more details).
Crispin Standards Track [Page 31]
RFC 2060 IMAP4rev1 December 1996
Server implementations are permitted to "hide" otherwise
accessible mailboxes from the wildcard characters, by preventing
certain characters or names from matching a wildcard in certain
situations. For example, a UNIX-based server might restrict the
interpretation of "*" so that an initial "/" character does not
match.
The special name INBOX is included in the output from LIST, if
INBOX is supported by this server for this user and if the
uppercase string "INBOX" matches the interpreted reference and
mailbox name arguments with wildcards as described above. The
criteria for omitting INBOX is whether SELECT INBOX will return
failure; it is not relevant whether the user's real INBOX resides
on this or some other server.
Example: C: A101 LIST "" ""
S: * LIST (\Noselect) "/" ""
S: A101 OK LIST Completed
C: A102 LIST #news.comp.mail.misc ""
S: * LIST (\Noselect) "." #news.
S: A102 OK LIST Completed
C: A103 LIST /usr/staff/jones ""
S: * LIST (\Noselect) "/" /
S: A103 OK LIST Completed
C: A202 LIST ~/Mail/ %
S: * LIST (\Noselect) "/" ~/Mail/foo
S: * LIST () "/" ~/Mail/meetings
S: A202 OK LIST completed
6.3.9. LSUB Command
Arguments: reference name
mailbox name with possible wildcards
Responses: untagged responses: LSUB
Result: OK - lsub completed
NO - lsub failure: can't list that reference or name
BAD - command unknown or arguments invalid
The LSUB command returns a subset of names from the set of names
that the user has declared as being "active" or "subscribed".
Zero or more untagged LSUB replies are returned. The arguments to
LSUB are in the same form as those for LIST.
A server MAY validate the subscribed names to see if they still
exist. If a name does not exist, it SHOULD be flagged with the
\Noselect attribute in the LSUB response. The server MUST NOT
Crispin Standards Track [Page 32]
RFC 2060 IMAP4rev1 December 1996
unilaterally remove an existing mailbox name from the subscription
list even if a mailbox by that name no longer exists.
Example: C: A002 LSUB "#news." "comp.mail.*"
S: * LSUB () "." #news.comp.mail.mime
S: * LSUB () "." #news.comp.mail.misc
S: A002 OK LSUB completed
6.3.10. STATUS Command
Arguments: mailbox name
status data item names
Responses: untagged responses: STATUS
Result: OK - status completed
NO - status failure: no status for that name
BAD - command unknown or arguments invalid
The STATUS command requests the status of the indicated mailbox.
It does not change the currently selected mailbox, nor does it
affect the state of any messages in the queried mailbox (in
particular, STATUS MUST NOT cause messages to lose the \Recent
flag).
The STATUS command provides an alternative to opening a second
IMAP4rev1 connection and doing an EXAMINE command on a mailbox to
query that mailbox's status without deselecting the current
mailbox in the first IMAP4rev1 connection.
Unlike the LIST command, the STATUS command is not guaranteed to
be fast in its response. In some implementations, the server is
obliged to open the mailbox read-only internally to obtain certain
status information. Also unlike the LIST command, the STATUS
command does not accept wildcards.
The currently defined status data items that can be requested are:
MESSAGES The number of messages in the mailbox.
RECENT The number of messages with the \Recent flag set.
UIDNEXT The next UID value that will be assigned to a new
message in the mailbox. It is guaranteed that this
value will not change unless new messages are added
to the mailbox; and that it will change when new
messages are added even if those new messages are
subsequently expunged.
Crispin Standards Track [Page 33]
RFC 2060 IMAP4rev1 December 1996
UIDVALIDITY The unique identifier validity value of the
mailbox.
UNSEEN The number of messages which do not have the \Seen
flag set.
Example: C: A042 STATUS blurdybloop (UIDNEXT MESSAGES)
S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
S: A042 OK STATUS completed
6.3.11. APPEND Command
Arguments: mailbox name
OPTIONAL flag parenthesized list
OPTIONAL date/time string
message literal
Responses: no specific responses for this command
Result: OK - append completed
NO - append error: can't append to that mailbox, error
in flags or date/time or message text
BAD - command unknown or arguments invalid
The APPEND command appends the literal argument as a new message
to the end of the specified destination mailbox. This argument
SHOULD be in the format of an [RFC-822] message. 8-bit characters
are permitted in the message. A server implementation that is
unable to preserve 8-bit data properly MUST be able to reversibly
convert 8-bit APPEND data to 7-bit using a [MIME-IMB] content
transfer encoding.
Note: There MAY be exceptions, e.g. draft messages, in which
required [RFC-822] header lines are omitted in the message literal
argument to APPEND. The full implications of doing so MUST be
understood and carefully weighed.
If a flag parenthesized list is specified, the flags SHOULD be set in
the resulting message; otherwise, the flag list of the resulting
message is set empty by default.
If a date_time is specified, the internal date SHOULD be set in the
resulting message; otherwise, the internal date of the resulting
message is set to the current date and time by default.
Crispin Standards Track [Page 34]
RFC 2060 IMAP4rev1 December 1996
If the append is unsuccessful for any reason, the mailbox MUST be
restored to its state before the APPEND attempt; no partial appending
is permitted.
If the destination mailbox does not exist, a server MUST return an
error, and MUST NOT automatically create the mailbox. Unless it is
certain that the destination mailbox can not be created, the server
MUST send the response code "[TRYCREATE]" as the prefix of the text
of the tagged NO response. This gives a hint to the client that it
can attempt a CREATE command and retry the APPEND if the CREATE is
successful.
If the mailbox is currently selected, the normal new mail actions
SHOULD occur. Specifically, the server SHOULD notify the client
immediately via an untagged EXISTS response. If the server does not
do so, the client MAY issue a NOOP command (or failing that, a CHECK
command) after one or more APPEND commands.
Example: C: A003 APPEND saved-messages (\Seen) {310}
C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
C: From: Fred Foobar <foobar@Blurdybloop.COM>
C: Subject: afternoon meeting
C: To: mooch@owatagu.siam.edu
C: Message-Id: <B27397-0100000@Blurdybloop.COM>
C: MIME-Version: 1.0
C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
C:
C: Hello Joe, do you think we can meet at 3:30 tomorrow?
C:
S: A003 OK APPEND completed
Note: the APPEND command is not used for message delivery, because
it does not provide a mechanism to transfer [SMTP] envelope
information.
6.4. Client Commands - Selected State
In selected state, commands that manipulate messages in a mailbox are
permitted.
In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
and the authenticated state commands (SELECT, EXAMINE, CREATE,
DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, and
APPEND), the following commands are valid in the selected state:
CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, STORE, COPY, and UID.
Crispin Standards Track [Page 35]
RFC 2060 IMAP4rev1 December 1996
6.4.1. CHECK Command
Arguments: none
Responses: no specific responses for this command
Result: OK - check completed
BAD - command unknown or arguments invalid
The CHECK command requests a checkpoint of the currently selected
mailbox. A checkpoint refers to any implementation-dependent
housekeeping associated with the mailbox (e.g. resolving the
server's in-memory state of the mailbox with the state on its
disk) that is not normally executed as part of each command. A
checkpoint MAY take a non-instantaneous amount of real time to
complete. If a server implementation has no such housekeeping
considerations, CHECK is equivalent to NOOP.
There is no guarantee that an EXISTS untagged response will happen
as a result of CHECK. NOOP, not CHECK, SHOULD be used for new
mail polling.
Example: C: FXXZ CHECK
S: FXXZ OK CHECK Completed
6.4.2. CLOSE Command
Arguments: none
Responses: no specific responses for this command
Result: OK - close completed, now in authenticated state
NO - close failure: no mailbox selected
BAD - command unknown or arguments invalid
The CLOSE command permanently removes from the currently selected
mailbox all messages that have the \Deleted flag set, and returns
to authenticated state from selected state. No untagged EXPUNGE
responses are sent.
No messages are removed, and no error is given, if the mailbox is
selected by an EXAMINE command or is otherwise selected read-only.
Even if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT
command MAY be issued without previously issuing a CLOSE command.
The SELECT, EXAMINE, and LOGOUT commands implicitly close the
currently selected mailbox without doing an expunge. However,
when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT
Crispin Standards Track [Page 36]
RFC 2060 IMAP4rev1 December 1996
sequence is considerably faster than an EXPUNGE-LOGOUT or
EXPUNGE-SELECT because no untagged EXPUNGE responses (which the
client would probably ignore) are sent.
Example: C: A341 CLOSE
S: A341 OK CLOSE completed
6.4.3. EXPUNGE Command
Arguments: none
Responses: untagged responses: EXPUNGE
Result: OK - expunge completed
NO - expunge failure: can't expunge (e.g. permission
denied)
BAD - command unknown or arguments invalid
The EXPUNGE command permanently removes from the currently
selected mailbox all messages that have the \Deleted flag set.
Before returning an OK to the client, an untagged EXPUNGE response
is sent for each message that is removed.
Example: C: A202 EXPUNGE
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: * 5 EXPUNGE
S: * 8 EXPUNGE
S: A202 OK EXPUNGE completed
Note: in this example, messages 3, 4, 7, and 11 had the
\Deleted flag set. See the description of the EXPUNGE
response for further explanation.
6.4.4. SEARCH Command
Arguments: OPTIONAL [CHARSET] specification
searching criteria (one or more)
Responses: REQUIRED untagged response: SEARCH
Result: OK - search completed
NO - search error: can't search that [CHARSET] or
criteria
BAD - command unknown or arguments invalid
Crispin Standards Track [Page 37]
RFC 2060 IMAP4rev1 December 1996
The SEARCH command searches the mailbox for messages that match
the given searching criteria. Searching criteria consist of one
or more search keys. The untagged SEARCH response from the server
contains a listing of message sequence numbers corresponding to
those messages that match the searching criteria.
When multiple keys are specified, the result is the intersection
(AND function) of all the messages that match those keys. For
example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers
to all deleted messages from Smith that were placed in the mailbox
since February 1, 1994. A search key can also be a parenthesized
list of one or more search keys (e.g. for use with the OR and NOT
keys).
Server implementations MAY exclude [MIME-IMB] body parts with
terminal content media types other than TEXT and MESSAGE from
consideration in SEARCH matching.
The OPTIONAL [CHARSET] specification consists of the word
"CHARSET" followed by a registered [CHARSET]. It indicates the
[CHARSET] of the strings that appear in the search criteria.
[MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in
[RFC-822]/[MIME-IMB] headers, MUST be decoded before comparing
text in a [CHARSET] other than US-ASCII. US-ASCII MUST be
supported; other [CHARSET]s MAY be supported. If the server does
not support the specified [CHARSET], it MUST return a tagged NO
response (not a BAD).
In all search keys that use strings, a message matches the key if
the string is a substring of the field. The matching is case-
insensitive.
The defined search keys are as follows. Refer to the Formal
Syntax section for the precise syntactic definitions of the
arguments.
<message set> Messages with message sequence numbers
corresponding to the specified message sequence
number set
ALL All messages in the mailbox; the default initial
key for ANDing.
ANSWERED Messages with the \Answered flag set.
BCC <string> Messages that contain the specified string in the
envelope structure's BCC field.
Crispin Standards Track [Page 38]
RFC 2060 IMAP4rev1 December 1996
BEFORE <date> Messages whose internal date is earlier than the
specified date.
BODY <string> Messages that contain the specified string in the
body of the message.
CC <string> Messages that contain the specified string in the
envelope structure's CC field.
DELETED Messages with the \Deleted flag set.
DRAFT Messages with the \Draft flag set.
FLAGGED Messages with the \Flagged flag set.
FROM <string> Messages that contain the specified string in the
envelope structure's FROM field.
HEADER <field-name> <string>
Messages that have a header with the specified
field-name (as defined in [RFC-822]) and that
contains the specified string in the [RFC-822]
field-body.
KEYWORD <flag> Messages with the specified keyword set.
LARGER <n> Messages with an [RFC-822] size larger than the
specified number of octets.
NEW Messages that have the \Recent flag set but not the
\Seen flag. This is functionally equivalent to
"(RECENT UNSEEN)".
NOT <search-key>
Messages that do not match the specified search
key.
OLD Messages that do not have the \Recent flag set.
This is functionally equivalent to "NOT RECENT" (as
opposed to "NOT NEW").
ON <date> Messages whose internal date is within the
specified date.
OR <search-key1> <search-key2>
Messages that match either search key.
RECENT Messages that have the \Recent flag set.
Crispin Standards Track [Page 39]
RFC 2060 IMAP4rev1 December 1996
SEEN Messages that have the \Seen flag set.
SENTBEFORE <date>
Messages whose [RFC-822] Date: header is earlier
than the specified date.
SENTON <date> Messages whose [RFC-822] Date: header is within the
specified date.
SENTSINCE <date>
Messages whose [RFC-822] Date: header is within or
later than the specified date.
SINCE <date> Messages whose internal date is within or later
than the specified date.
SMALLER <n> Messages with an [RFC-822] size smaller than the
specified number of octets.
SUBJECT <string>
Messages that contain the specified string in the
envelope structure's SUBJECT field.
TEXT <string> Messages that contain the specified string in the
header or body of the message.
TO <string> Messages that contain the specified string in the
envelope structure's TO field.
UID <message set>
Messages with unique identifiers corresponding to
the specified unique identifier set.
UNANSWERED Messages that do not have the \Answered flag set.
UNDELETED Messages that do not have the \Deleted flag set.
UNDRAFT Messages that do not have the \Draft flag set.
UNFLAGGED Messages that do not have the \Flagged flag set.
UNKEYWORD <flag>
Messages that do not have the specified keyword
set.
UNSEEN Messages that do not have the \Seen flag set.
Crispin Standards Track [Page 40]
RFC 2060 IMAP4rev1 December 1996
Example: C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"
S: * SEARCH 2 84 882
S: A282 OK SEARCH completed
6.4.5. FETCH Command
Arguments: message set
message data item names
Responses: untagged responses: FETCH
Result: OK - fetch completed
NO - fetch error: can't fetch that data
BAD - command unknown or arguments invalid
The FETCH command retrieves data associated with a message in the
mailbox. The data items to be fetched can be either a single atom
or a parenthesized list.
The currently defined data items that can be fetched are:
ALL Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE ENVELOPE)
BODY Non-extensible form of BODYSTRUCTURE.
BODY[<section>]<<partial>>
The text of a particular body section. The section
specification is a set of zero or more part
specifiers delimited by periods. A part specifier
is either a part number or one of the following:
HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, MIME, and
TEXT. An empty section specification refers to the
entire message, including the header.
Every message has at least one part number.
Non-[MIME-IMB] messages, and non-multipart
[MIME-IMB] messages with no encapsulated message,
only have a part 1.
Multipart messages are assigned consecutive part
numbers, as they occur in the message. If a
particular part is of type message or multipart,
its parts MUST be indicated by a period followed by
the part number within that nested multipart part.
Crispin Standards Track [Page 41]
RFC 2060 IMAP4rev1 December 1996
A part of type MESSAGE/RFC822 also has nested part
numbers, referring to parts of the MESSAGE part's
body.
The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and
TEXT part specifiers can be the sole part specifier
or can be prefixed by one or more numeric part
specifiers, provided that the numeric part
specifier refers to a part of type MESSAGE/RFC822.
The MIME part specifier MUST be prefixed by one or
more numeric part specifiers.
The HEADER, HEADER.FIELDS, and HEADER.FIELDS.NOT
part specifiers refer to the [RFC-822] header of
the message or of an encapsulated [MIME-IMT]
MESSAGE/RFC822 message. HEADER.FIELDS and
HEADER.FIELDS.NOT are followed by a list of
field-name (as defined in [RFC-822]) names, and
return a subset of the header. The subset returned
by HEADER.FIELDS contains only those header fields
with a field-name that matches one of the names in
the list; similarly, the subset returned by
HEADER.FIELDS.NOT contains only the header fields
with a non-matching field-name. The field-matching
is case-insensitive but otherwise exact. In all
cases, the delimiting blank line between the header
and the body is always included.
The MIME part specifier refers to the [MIME-IMB]
header for this part.
The TEXT part specifier refers to the text body of
the message, omitting the [RFC-822] header.
Crispin Standards Track [Page 42]
RFC 2060 IMAP4rev1 December 1996
Here is an example of a complex message
with some of its part specifiers:
HEADER ([RFC-822] header of the message)
TEXT MULTIPART/MIXED
1 TEXT/PLAIN
2 APPLICATION/OCTET-STREAM
3 MESSAGE/RFC822
3.HEADER ([RFC-822] header of the message)
3.TEXT ([RFC-822] text body of the message)
3.1 TEXT/PLAIN
3.2 APPLICATION/OCTET-STREAM
4 MULTIPART/MIXED
4.1 IMAGE/GIF
4.1.MIME ([MIME-IMB] header for the IMAGE/GIF)
4.2 MESSAGE/RFC822
4.2.HEADER ([RFC-822] header of the message)
4.2.TEXT ([RFC-822] text body of the message)
4.2.1 TEXT/PLAIN
4.2.2 MULTIPART/ALTERNATIVE
4.2.2.1 TEXT/PLAIN
4.2.2.2 TEXT/RICHTEXT
It is possible to fetch a substring of the
designated text. This is done by appending an open
angle bracket ("<"), the octet position of the
first desired octet, a period, the maximum number
of octets desired, and a close angle bracket (">")
to the part specifier. If the starting octet is
beyond the end of the text, an empty string is
returned.
Any partial fetch that attempts to read beyond the
end of the text is truncated as appropriate. A
partial fetch that starts at octet 0 is returned as
a partial fetch, even if this truncation happened.
Note: this means that BODY[]<0.2048> of a
1500-octet message will return BODY[]<0>
with a literal of size 1500, not BODY[].
Note: a substring fetch of a
HEADER.FIELDS or HEADER.FIELDS.NOT part
specifier is calculated after subsetting
the header.
Crispin Standards Track [Page 43]
RFC 2060 IMAP4rev1 December 1996
The \Seen flag is implicitly set; if this causes
the flags to change they SHOULD be included as part
of the FETCH responses.
BODY.PEEK[<section>]<<partial>>
An alternate form of BODY[<section>] that does not
implicitly set the \Seen flag.
BODYSTRUCTURE The [MIME-IMB] body structure of the message. This
is computed by the server by parsing the [MIME-IMB]
header fields in the [RFC-822] header and
[MIME-IMB] headers.
ENVELOPE The envelope structure of the message. This is
computed by the server by parsing the [RFC-822]
header into the component parts, defaulting various
fields as necessary.
FAST Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE)
FLAGS The flags that are set for this message.
FULL Macro equivalent to: (FLAGS INTERNALDATE
RFC822.SIZE ENVELOPE BODY)
INTERNALDATE The internal date of the message.
RFC822 Functionally equivalent to BODY[], differing in the
syntax of the resulting untagged FETCH data (RFC822
is returned).
RFC822.HEADER Functionally equivalent to BODY.PEEK[HEADER],
differing in the syntax of the resulting untagged
FETCH data (RFC822.HEADER is returned).
RFC822.SIZE The [RFC-822] size of the message.
RFC822.TEXT Functionally equivalent to BODY[TEXT], differing in
the syntax of the resulting untagged FETCH data
(RFC822.TEXT is returned).
UID The unique identifier for the message.
Crispin Standards Track [Page 44]
RFC 2060 IMAP4rev1 December 1996
Example: C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
S: * 2 FETCH ....
S: * 3 FETCH ....
S: * 4 FETCH ....
S: A654 OK FETCH completed
6.4.6. STORE Command
Arguments: message set
message data item name
value for message data item
Responses: untagged responses: FETCH
Result: OK - store completed
NO - store error: can't store that data
BAD - command unknown or arguments invalid
The STORE command alters data associated with a message in the
mailbox. Normally, STORE will return the updated value of the
data with an untagged FETCH response. A suffix of ".SILENT" in
the data item name prevents the untagged FETCH, and the server
SHOULD assume that the client has determined the updated value
itself or does not care about the updated value.
Note: regardless of whether or not the ".SILENT" suffix was
used, the server SHOULD send an untagged FETCH response if a
change to a message's flags from an external source is
observed. The intent is that the status of the flags is
determinate without a race condition.
The currently defined data items that can be stored are:
FLAGS <flag list>
Replace the flags for the message with the
argument. The new value of the flags are returned
as if a FETCH of those flags was done.
FLAGS.SILENT <flag list>
Equivalent to FLAGS, but without returning a new
value.
+FLAGS <flag list>
Add the argument to the flags for the message. The
new value of the flags are returned as if a FETCH
of those flags was done.
Crispin Standards Track [Page 45]
RFC 2060 IMAP4rev1 December 1996
+FLAGS.SILENT <flag list>
Equivalent to +FLAGS, but without returning a new
value.
-FLAGS <flag list>
Remove the argument from the flags for the message.
The new value of the flags are returned as if a
FETCH of those flags was done.
-FLAGS.SILENT <flag list>
Equivalent to -FLAGS, but without returning a new
value.
Example: C: A003 STORE 2:4 +FLAGS (\Deleted)
S: * 2 FETCH FLAGS (\Deleted \Seen)
S: * 3 FETCH FLAGS (\Deleted)
S: * 4 FETCH FLAGS (\Deleted \Flagged \Seen)
S: A003 OK STORE completed
6.4.7. COPY Command
Arguments: message set
mailbox name
Responses: no specific responses for this command
Result: OK - copy completed
NO - copy error: can't copy those messages or to that
name
BAD - command unknown or arguments invalid
The COPY command copies the specified message(s) to the end of the
specified destination mailbox. The flags and internal date of the
message(s) SHOULD be preserved in the copy.
If the destination mailbox does not exist, a server SHOULD return
an error. It SHOULD NOT automatically create the mailbox. Unless
it is certain that the destination mailbox can not be created, the
server MUST send the response code "[TRYCREATE]" as the prefix of
the text of the tagged NO response. This gives a hint to the
client that it can attempt a CREATE command and retry the COPY if
the CREATE is successful.
Crispin Standards Track [Page 46]
RFC 2060 IMAP4rev1 December 1996
If the COPY command is unsuccessful for any reason, server
implementations MUST restore the destination mailbox to its state
before the COPY attempt.
Example: C: A003 COPY 2:4 MEETING
S: A003 OK COPY completed
6.4.8. UID Command
Arguments: command name
command arguments
Responses: untagged responses: FETCH, SEARCH
Result: OK - UID command completed
NO - UID command error
BAD - command unknown or arguments invalid
The UID command has two forms. In the first form, it takes as its
arguments a COPY, FETCH, or STORE command with arguments
appropriate for the associated command. However, the numbers in
the message set argument are unique identifiers instead of message
sequence numbers.
In the second form, the UID command takes a SEARCH command with
SEARCH command arguments. The interpretation of the arguments is
the same as with SEARCH; however, the numbers returned in a SEARCH
response for a UID SEARCH command are unique identifiers instead
of message sequence numbers. For example, the command UID SEARCH
1:100 UID 443:557 returns the unique identifiers corresponding to
the intersection of the message sequence number set 1:100 and the
UID set 443:557.
Message set ranges are permitted; however, there is no guarantee
that unique identifiers be contiguous. A non-existent unique
identifier within a message set range is ignored without any error
message generated.
The number after the "*" in an untagged FETCH response is always a
message sequence number, not a unique identifier, even for a UID
command response. However, server implementations MUST implicitly
include the UID message data item as part of any FETCH response
caused by a UID command, regardless of whether a UID was specified
as a message data item to the FETCH.
Crispin Standards Track [Page 47]
RFC 2060 IMAP4rev1 December 1996
Example: C: A999 UID FETCH 4827313:4828442 FLAGS
S: * 23 FETCH (FLAGS (\Seen) UID 4827313)
S: * 24 FETCH (FLAGS (\Seen) UID 4827943)
S: * 25 FETCH (FLAGS (\Seen) UID 4828442)
S: A999 UID FETCH completed
6.5. Client Commands - Experimental/Expansion
6.5.1. X<atom> Command
Arguments: implementation defined
Responses: implementation defined
Result: OK - command completed
NO - failure
BAD - command unknown or arguments invalid
Any command prefixed with an X is an experimental command.
Commands which are not part of this specification, a standard or
standards-track revision of this specification, or an IESG-
approved experimental protocol, MUST use the X prefix.
Any added untagged responses issued by an experimental command
MUST also be prefixed with an X. Server implementations MUST NOT
send any such untagged responses, unless the client requested it
by issuing the associated experimental command.
Example: C: a441 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4 XPIG-LATIN
S: a441 OK CAPABILITY completed
C: A442 XPIG-LATIN
S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay
S: A442 OK XPIG-LATIN ompleted-cay
7. Server Responses
Server responses are in three forms: status responses, server data,
and command continuation request. The information contained in a
server response, identified by "Contents:" in the response
descriptions below, is described by function, not by syntax. The
precise syntax of server responses is described in the Formal Syntax
section.
The client MUST be prepared to accept any response at all times.
Crispin Standards Track [Page 48]
RFC 2060 IMAP4rev1 December 1996
Status responses can be tagged or untagged. Tagged status responses
indicate the completion result (OK, NO, or BAD status) of a client
command, and have a tag matching the command.
Some status responses, and all server data, are untagged. An
untagged response is indicated by the token "*" instead of a tag.
Untagged status responses indicate server greeting, or server status
that does not indicate the completion of a command (for example, an
impending system shutdown alert). For historical reasons, untagged
server data responses are also called "unsolicited data", although
strictly speaking only unilateral server data is truly "unsolicited".
Certain server data MUST be recorded by the client when it is
received; this is noted in the description of that data. Such data
conveys critical information which affects the interpretation of all
subsequent commands and responses (e.g. updates reflecting the
creation or destruction of messages).
Other server data SHOULD be recorded for later reference; if the
client does not need to record the data, or if recording the data has
no obvious purpose (e.g. a SEARCH response when no SEARCH command is
in progress), the data SHOULD be ignored.
An example of unilateral untagged server data occurs when the IMAP
connection is in selected state. In selected state, the server
checks the mailbox for new messages as part of command execution.
Normally, this is part of the execution of every command; hence, a
NOOP command suffices to check for new messages. If new messages are
found, the server sends untagged EXISTS and RECENT responses
reflecting the new size of the mailbox. Server implementations that
offer multiple simultaneous access to the same mailbox SHOULD also
send appropriate unilateral untagged FETCH and EXPUNGE responses if
another agent changes the state of any message flags or expunges any
messages.
Command continuation request responses use the token "+" instead of a
tag. These responses are sent by the server to indicate acceptance
of an incomplete client command and readiness for the remainder of
the command.
7.1. Server Responses - Status Responses
Status responses are OK, NO, BAD, PREAUTH and BYE. OK, NO, and BAD
may be tagged or untagged. PREAUTH and BYE are always untagged.
Status responses MAY include an OPTIONAL "response code". A response
code consists of data inside square brackets in the form of an atom,
possibly followed by a space and arguments. The response code
Crispin Standards Track [Page 49]
RFC 2060 IMAP4rev1 December 1996
contains additional information or status codes for client software
beyond the OK/NO/BAD condition, and are defined when there is a
specific action that a client can take based upon the additional
information.
The currently defined response codes are:
ALERT 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.
NEWNAME Followed by a mailbox name and a new mailbox name.
A SELECT or EXAMINE is failing because the target
mailbox name no longer exists because it was
renamed to the new mailbox name. This is a hint to
the client that the operation can succeed if the
SELECT or EXAMINE is reissued with the new mailbox
name.
PARSE The human-readable text represents an error in
parsing the [RFC-822] header or [MIME-IMB] headers
of a message in the mailbox.
PERMANENTFLAGS Followed by a parenthesized list of flags,
indicates which of the known flags that the client
can change permanently. Any flags that are in the
FLAGS untagged response, but not the PERMANENTFLAGS
list, can not be set permanently. If the client
attempts to STORE a flag that is not in the
PERMANENTFLAGS list, the server will either reject
it with a NO reply or store the state for the
remainder of the current session only. The
PERMANENTFLAGS list can also include the special
flag \*, which indicates that it is possible to
create new keywords by attempting to store those
flags in the mailbox.
READ-ONLY The mailbox is selected read-only, or its access
while selected has changed from read-write to
read-only.
READ-WRITE The mailbox is selected read-write, or its access
while selected has changed from read-only to
read-write.
Crispin Standards Track [Page 50]
RFC 2060 IMAP4rev1 December 1996
TRYCREATE An APPEND or COPY attempt is failing because the
target mailbox does not exist (as opposed to some
other reason). This is a hint to the client that
the operation can succeed if the mailbox is first
created by the CREATE command.
UIDVALIDITY Followed by a decimal number, indicates the unique
identifier validity value.
UNSEEN Followed by a decimal number, indicates the number
of the first message without the \Seen flag set.
Additional response codes defined by particular client or server
implementations SHOULD be prefixed with an "X" until they are
added to a revision of this protocol. Client implementations
SHOULD ignore response codes that they do not recognize.
7.1.1. OK Response
Contents: OPTIONAL response code
human-readable text
The OK response indicates an information message from the server.
When tagged, it indicates successful completion of the associated
command. The human-readable text MAY be presented to the user as
an information message. The untagged form indicates an
information-only message; the nature of the information MAY be
indicated by a response code.
The untagged form is also used as one of three possible greetings
at connection startup. It indicates that the connection is not
yet authenticated and that a LOGIN command is needed.
Example: S: * OK IMAP4rev1 server ready
C: A001 LOGIN fred blurdybloop
S: * OK [ALERT] System shutdown in 10 minutes
S: A001 OK LOGIN Completed
7.1.2. NO Response
Contents: OPTIONAL response code
human-readable text
The NO response indicates an operational error message from the
server. When tagged, it indicates unsuccessful completion of the
associated command. The untagged form indicates a warning; the
command can still complete successfully. The human-readable text
describes the condition.
Crispin Standards Track [Page 51]
RFC 2060 IMAP4rev1 December 1996
Example: C: A222 COPY 1:2 owatagusiam
S: * NO Disk is 98% full, please delete unnecessary data
S: A222 OK COPY completed
C: A223 COPY 3:200 blurdybloop
S: * NO Disk is 98% full, please delete unnecessary data
S: * NO Disk is 99% full, please delete unnecessary data
S: A223 NO COPY failed: disk is full
7.1.3. BAD Response
Contents: OPTIONAL response code
human-readable text
The BAD response indicates an error message from the server. When
tagged, it reports a protocol-level error in the client's command;
the tag indicates the command that caused the error. The untagged
form indicates a protocol-level error for which the associated
command can not be determined; it can also indicate an internal
server failure. The human-readable text describes the condition.
Example: C: ...very long command line...
S: * BAD Command line too long
C: ...empty line...
S: * BAD Empty command line
C: A443 EXPUNGE
S: * BAD Disk crash, attempting salvage to a new disk!
S: * OK Salvage successful, no data lost
S: A443 OK Expunge completed
7.1.4. PREAUTH Response
Contents: OPTIONAL response code
human-readable text
The PREAUTH response is always untagged, and is one of three
possible greetings at connection startup. It indicates that the
connection has already been authenticated by external means and
thus no LOGIN command is needed.
Example: S: * PREAUTH IMAP4rev1 server logged in as Smith
7.1.5. BYE Response
Contents: OPTIONAL response code
human-readable text
Crispin Standards Track [Page 52]
RFC 2060 IMAP4rev1 December 1996
The BYE response is always untagged, and indicates that the server
is about to close the connection. The human-readable text MAY be
displayed to the user in a status report by the client. The BYE
response is sent under one of four conditions:
1) as part of a normal logout sequence. The server will close
the connection after sending the tagged OK response to the
LOGOUT command.
2) as a panic shutdown announcement. The server closes the
connection immediately.
3) as an announcement of an inactivity autologout. The server
closes the connection immediately.
4) as one of three possible greetings at connection startup,
indicating that the server is not willing to accept a
connection from this client. The server closes the
connection immediately.
The difference between a BYE that occurs as part of a normal
LOGOUT sequence (the first case) and a BYE that occurs because of
a failure (the other three cases) is that the connection closes
immediately in the failure case.
Example: S: * BYE Autologout; idle for too long
7.2. Server Responses - Server and Mailbox Status
These responses are always untagged. This is how server and mailbox
status data are transmitted from the server to the client. Many of
these responses typically result from a command with the same name.
7.2.1. CAPABILITY Response
Contents: capability listing
The CAPABILITY response occurs as a result of a CAPABILITY
command. The capability listing contains a space-separated
listing of capability names that the server supports. The
capability listing MUST include the atom "IMAP4rev1".
A capability name which begins with "AUTH=" indicates that the
server supports that particular authentication mechanism.
Crispin Standards Track [Page 53]
RFC 2060 IMAP4rev1 December 1996
Other capability names indicate that the server supports an
extension, revision, or amendment to the IMAP4rev1 protocol.
Server responses MUST conform to this document until the client
issues a command that uses the associated capability.
Capability names MUST either begin with "X" or be standard or
standards-track IMAP4rev1 extensions, revisions, or amendments
registered with IANA. A server MUST NOT offer unregistered or
non-standard capability names, unless such names are prefixed with
an "X".
Client implementations SHOULD NOT require any capability name
other than "IMAP4rev1", and MUST ignore any unknown capability
names.
Example: S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4 XPIG-LATIN
7.2.2. LIST Response
Contents: name attributes
hierarchy delimiter
name
The LIST response occurs as a result of a LIST command. It
returns a single name that matches the LIST specification. There
can be multiple LIST responses for a single LIST command.
Four name attributes are defined:
\Noinferiors It is not possible for any child levels of
hierarchy to exist under this name; no child levels
exist now and none can be created in the future.
\Noselect It is not possible to use this name as a selectable
mailbox.
\Marked The mailbox has been marked "interesting" by the
server; the mailbox probably contains messages that
have been added since the last time the mailbox was
selected.
\Unmarked The mailbox does not contain any additional
messages since the last time the mailbox was
selected.
If it is not feasible for the server to determine whether the
mailbox is "interesting" or not, or if the name is a \Noselect
name, the server SHOULD NOT send either \Marked or \Unmarked.
Crispin Standards Track [Page 54]
RFC 2060 IMAP4rev1 December 1996
The hierarchy delimiter is a character used to delimit levels of
hierarchy in a mailbox name. A client can use it to create child
mailboxes, and to search higher or lower levels of naming
hierarchy. All children of a top-level hierarchy node MUST use
the same separator character. A NIL hierarchy delimiter means
that no hierarchy exists; the name is a "flat" name.
The name represents an unambiguous left-to-right hierarchy, and
MUST be valid for use as a reference in LIST and LSUB commands.
Unless \Noselect is indicated, the name MUST also be valid as an
argument for commands, such as SELECT, that accept mailbox
names.
Example: S: * LIST (\Noselect) "/" ~/Mail/foo
7.2.3. LSUB Response
Contents: name attributes
hierarchy delimiter
name
The LSUB response occurs as a result of an LSUB command. It
returns a single name that matches the LSUB specification. There
can be multiple LSUB responses for a single LSUB command. The
data is identical in format to the LIST response.
Example: S: * LSUB () "." #news.comp.mail.misc
7.2.4 STATUS Response
Contents: name
status parenthesized list
The STATUS response occurs as a result of an STATUS command. It
returns the mailbox name that matches the STATUS specification and
the requested mailbox status information.
Example: S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
7.2.5. SEARCH Response
Contents: zero or more numbers
To Next Section