Use PBKDF2 with HMAC-SHA1 for master passphrase in clawsrc.
[claws.git] / doc / src / rfc3501.txt
1
2
3
4
5
6
7 Network Working Group                                         M. Crispin
8 Request for Comments: 3501                      University of Washington
9 Obsoletes: 2060                                               March 2003
10 Category: Standards Track
11
12
13             INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
14
15 Status of this Memo
16
17    This document specifies an Internet standards track protocol for the
18    Internet community, and requests discussion and suggestions for
19    improvements.  Please refer to the current edition of the "Internet
20    Official Protocol Standards" (STD 1) for the standardization state
21    and status of this protocol.  Distribution of this memo is unlimited.
22
23 Copyright Notice
24
25    Copyright (C) The Internet Society (2003).  All Rights Reserved.
26
27 Abstract
28
29    The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1)
30    allows a client to access and manipulate electronic mail messages on
31    a server.  IMAP4rev1 permits manipulation of mailboxes (remote
32    message folders) in a way that is functionally equivalent to local
33    folders.  IMAP4rev1 also provides the capability for an offline
34    client to resynchronize with the server.
35
36    IMAP4rev1 includes operations for creating, deleting, and renaming
37    mailboxes, checking for new messages, permanently removing messages,
38    setting and clearing flags, RFC 2822 and RFC 2045 parsing, searching,
39    and selective fetching of message attributes, texts, and portions
40    thereof.  Messages in IMAP4rev1 are accessed by the use of numbers.
41    These numbers are either message sequence numbers or unique
42    identifiers.
43
44    IMAP4rev1 supports a single server.  A mechanism for accessing
45    configuration information to support multiple IMAP4rev1 servers is
46    discussed in RFC 2244.
47
48    IMAP4rev1 does not specify a means of posting mail; this function is
49    handled by a mail transfer protocol such as RFC 2821.
50
51
52
53
54
55
56
57
58 Crispin                     Standards Track                     [Page 1]
59 \f
60 RFC 3501                         IMAPv4                       March 2003
61
62
63 Table of Contents
64
65    IMAP4rev1 Protocol Specification ................................  4
66    1.      How to Read This Document ...............................  4
67    1.1.    Organization of This Document ...........................  4
68    1.2.    Conventions Used in This Document .......................  4
69    1.3.    Special Notes to Implementors ...........................  5
70    2.      Protocol Overview .......................................  6
71    2.1.    Link Level ..............................................  6
72    2.2.    Commands and Responses ..................................  6
73    2.2.1.  Client Protocol Sender and Server Protocol Receiver .....  6
74    2.2.2.  Server Protocol Sender and Client Protocol Receiver .....  7
75    2.3.    Message Attributes ......................................  8
76    2.3.1.  Message Numbers .........................................  8
77    2.3.1.1.        Unique Identifier (UID) Message Attribute .......  8
78    2.3.1.2.        Message Sequence Number Message Attribute ....... 10
79    2.3.2.  Flags Message Attribute ................................. 11
80    2.3.3.  Internal Date Message Attribute ......................... 12
81    2.3.4.  [RFC-2822] Size Message Attribute ....................... 12
82    2.3.5.  Envelope Structure Message Attribute .................... 12
83    2.3.6.  Body Structure Message Attribute ........................ 12
84    2.4.    Message Texts ........................................... 13
85    3.      State and Flow Diagram .................................. 13
86    3.1.    Not Authenticated State ................................. 13
87    3.2.    Authenticated State ..................................... 13
88    3.3.    Selected State .......................................... 13
89    3.4.    Logout State ............................................ 14
90    4.      Data Formats ............................................ 16
91    4.1.    Atom .................................................... 16
92    4.2.    Number .................................................. 16
93    4.3.    String .................................................. 16
94    4.3.1.  8-bit and Binary Strings ................................ 17
95    4.4.    Parenthesized List ...................................... 17
96    4.5.    NIL ..................................................... 17
97    5.      Operational Considerations .............................. 18
98    5.1.    Mailbox Naming .......................................... 18
99    5.1.1.  Mailbox Hierarchy Naming ................................ 19
100    5.1.2.  Mailbox Namespace Naming Convention ..................... 19
101    5.1.3.  Mailbox International Naming Convention ................. 19
102    5.2.    Mailbox Size and Message Status Updates ................. 21
103    5.3.    Response when no Command in Progress .................... 21
104    5.4.    Autologout Timer ........................................ 22
105    5.5.    Multiple Commands in Progress ........................... 22
106    6.      Client Commands ........................................  23
107    6.1.    Client Commands - Any State ............................  24
108    6.1.1.  CAPABILITY Command .....................................  24
109    6.1.2.  NOOP Command ...........................................  25
110    6.1.3.  LOGOUT Command .........................................  26
111
112
113
114 Crispin                     Standards Track                     [Page 2]
115 \f
116 RFC 3501                         IMAPv4                       March 2003
117
118
119    6.2.    Client Commands - Not Authenticated State ..............  26
120    6.2.1.  STARTTLS Command .......................................  27
121    6.2.2.  AUTHENTICATE Command ...................................  28
122    6.2.3.  LOGIN Command ..........................................  30
123    6.3.    Client Commands - Authenticated State ..................  31
124    6.3.1.  SELECT Command .........................................  32
125    6.3.2.  EXAMINE Command ........................................  34
126    6.3.3.  CREATE Command .........................................  34
127    6.3.4.  DELETE Command .........................................  35
128    6.3.5.  RENAME Command .........................................  37
129    6.3.6.  SUBSCRIBE Command ......................................  39
130    6.3.7.  UNSUBSCRIBE Command ....................................  39
131    6.3.8.  LIST Command ...........................................  40
132    6.3.9.  LSUB Command ...........................................  43
133    6.3.10. STATUS Command .........................................  44
134    6.3.11. APPEND Command .........................................  46
135    6.4.    Client Commands - Selected State .......................  47
136    6.4.1.  CHECK Command ..........................................  47
137    6.4.2.  CLOSE Command ..........................................  48
138    6.4.3.  EXPUNGE Command ........................................  49
139    6.4.4.  SEARCH Command .........................................  49
140    6.4.5.  FETCH Command ..........................................  54
141    6.4.6.  STORE Command ..........................................  58
142    6.4.7.  COPY Command ...........................................  59
143    6.4.8.  UID Command ............................................  60
144    6.5.    Client Commands - Experimental/Expansion ...............  62
145    6.5.1.  X<atom> Command ........................................  62
146    7.      Server Responses .......................................  62
147    7.1.    Server Responses - Status Responses ....................  63
148    7.1.1.  OK Response ............................................  65
149    7.1.2.  NO Response ............................................  66
150    7.1.3.  BAD Response ...........................................  66
151    7.1.4.  PREAUTH Response .......................................  67
152    7.1.5.  BYE Response ...........................................  67
153    7.2.    Server Responses - Server and Mailbox Status ...........  68
154    7.2.1.  CAPABILITY Response ....................................  68
155    7.2.2.  LIST Response ..........................................  69
156    7.2.3.  LSUB Response ..........................................  70
157    7.2.4   STATUS Response ........................................  70
158    7.2.5.  SEARCH Response ........................................  71
159    7.2.6.  FLAGS Response .........................................  71
160    7.3.    Server Responses - Mailbox Size ........................  71
161    7.3.1.  EXISTS Response ........................................  71
162    7.3.2.  RECENT Response ........................................  72
163    7.4.    Server Responses - Message Status ......................  72
164    7.4.1.  EXPUNGE Response .......................................  72
165    7.4.2.  FETCH Response .........................................  73
166    7.5.    Server Responses - Command Continuation Request ........  79
167
168
169
170 Crispin                     Standards Track                     [Page 3]
171 \f
172 RFC 3501                         IMAPv4                       March 2003
173
174
175    8.      Sample IMAP4rev1 connection ............................  80
176    9.      Formal Syntax ..........................................  81
177    10.     Author's Note ..........................................  92
178    11.     Security Considerations ................................  92
179    11.1.   STARTTLS Security Considerations .......................  92
180    11.2.   Other Security Considerations ..........................  93
181    12.     IANA Considerations ....................................  94
182    Appendices .....................................................  95
183    A.      References .............................................  95
184    B.      Changes from RFC 2060 ..................................  97
185    C.      Key Word Index ......................................... 103
186    Author's Address ............................................... 107
187    Full Copyright Statement ....................................... 108
188
189 IMAP4rev1 Protocol Specification
190
191 1.      How to Read This Document
192
193 1.1.    Organization of This Document
194
195    This document is written from the point of view of the implementor of
196    an IMAP4rev1 client or server.  Beyond the protocol overview in
197    section 2, it is not optimized for someone trying to understand the
198    operation of the protocol.  The material in sections 3 through 5
199    provides the general context and definitions with which IMAP4rev1
200    operates.
201
202    Sections 6, 7, and 9 describe the IMAP commands, responses, and
203    syntax, respectively.  The relationships among these are such that it
204    is almost impossible to understand any of them separately.  In
205    particular, do not attempt to deduce command syntax from the command
206    section alone; instead refer to the Formal Syntax section.
207
208 1.2.    Conventions Used in This Document
209
210    "Conventions" are basic principles or procedures.  Document
211    conventions are noted in this section.
212
213    In examples, "C:" and "S:" indicate lines sent by the client and
214    server respectively.
215
216    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
217    "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to
218    be interpreted as described in [KEYWORDS].
219
220    The word "can" (not "may") is used to refer to a possible
221    circumstance or situation, as opposed to an optional facility of the
222    protocol.
223
224
225
226 Crispin                     Standards Track                     [Page 4]
227 \f
228 RFC 3501                         IMAPv4                       March 2003
229
230
231    "User" is used to refer to a human user, whereas "client" refers to
232    the software being run by the user.
233
234    "Connection" refers to the entire sequence of client/server
235    interaction from the initial establishment of the network connection
236    until its termination.
237
238    "Session" refers to the sequence of client/server interaction from
239    the time that a mailbox is selected (SELECT or EXAMINE command) until
240    the time that selection ends (SELECT or EXAMINE of another mailbox,
241    CLOSE command, or connection termination).
242
243    Characters are 7-bit US-ASCII unless otherwise specified.  Other
244    character sets are indicated using a "CHARSET", as described in
245    [MIME-IMT] and defined in [CHARSET].  CHARSETs have important
246    additional semantics in addition to defining character set; refer to
247    these documents for more detail.
248
249    There are several protocol conventions in IMAP.  These refer to
250    aspects of the specification which are not strictly part of the IMAP
251    protocol, but reflect generally-accepted practice.  Implementations
252    need to be aware of these conventions, and avoid conflicts whether or
253    not they implement the convention.  For example, "&" may not be used
254    as a hierarchy delimiter since it conflicts with the Mailbox
255    International Naming Convention, and other uses of "&" in mailbox
256    names are impacted as well.
257
258 1.3.    Special Notes to Implementors
259
260    Implementors of the IMAP protocol are strongly encouraged to read the
261    IMAP implementation recommendations document [IMAP-IMPLEMENTATION] in
262    conjunction with this document, to help understand the intricacies of
263    this protocol and how best to build an interoperable product.
264
265    IMAP4rev1 is designed to be upwards compatible from the [IMAP2] and
266    unpublished IMAP2bis protocols.  IMAP4rev1 is largely compatible with
267    the IMAP4 protocol described in RFC 1730; the exception being in
268    certain facilities added in RFC 1730 that proved problematic and were
269    subsequently removed.  In the course of the evolution of IMAP4rev1,
270    some aspects in the earlier protocols have become obsolete.  Obsolete
271    commands, responses, and data formats which an IMAP4rev1
272    implementation can encounter when used with an earlier implementation
273    are described in [IMAP-OBSOLETE].
274
275    Other compatibility issues with IMAP2bis, the most common variant of
276    the earlier protocol, are discussed in [IMAP-COMPAT].  A full
277    discussion of compatibility issues with rare (and presumed extinct)
278
279
280
281
282 Crispin                     Standards Track                     [Page 5]
283 \f
284 RFC 3501                         IMAPv4                       March 2003
285
286
287    variants of [IMAP2] is in [IMAP-HISTORICAL]; this document is
288    primarily of historical interest.
289
290    IMAP was originally developed for the older [RFC-822] standard, and
291    as a consequence several fetch items in IMAP incorporate "RFC822" in
292    their name.  With the exception of RFC822.SIZE, there are more modern
293    replacements; for example, the modern version of RFC822.HEADER is
294    BODY.PEEK[HEADER].  In all cases, "RFC822" should be interpreted as a
295    reference to the updated [RFC-2822] standard.
296
297 2.      Protocol Overview
298
299 2.1.    Link Level
300
301    The IMAP4rev1 protocol assumes a reliable data stream such as that
302    provided by TCP.  When TCP is used, an IMAP4rev1 server listens on
303    port 143.
304
305 2.2.    Commands and Responses
306
307    An IMAP4rev1 connection consists of the establishment of a
308    client/server network connection, an initial greeting from the
309    server, and client/server interactions.  These client/server
310    interactions consist of a client command, server data, and a server
311    completion result response.
312
313    All interactions transmitted by client and server are in the form of
314    lines, that is, strings that end with a CRLF.  The protocol receiver
315    of an IMAP4rev1 client or server is either reading a line, or is
316    reading a sequence of octets with a known count followed by a line.
317
318 2.2.1.  Client Protocol Sender and Server Protocol Receiver
319
320    The client command begins an operation.  Each client command is
321    prefixed with an identifier (typically a short alphanumeric string,
322    e.g., A0001, A0002, etc.) called a "tag".  A different tag is
323    generated by the client for each command.
324
325    Clients MUST follow the syntax outlined in this specification
326    strictly.  It is a syntax error to send a command with missing or
327    extraneous spaces or arguments.
328
329    There are two cases in which a line from the client does not
330    represent a complete command.  In one case, a command argument is
331    quoted with an octet count (see the description of literal in String
332    under Data Formats); in the other case, the command arguments require
333    server feedback (see the AUTHENTICATE command).  In either case, the
334
335
336
337
338 Crispin                     Standards Track                     [Page 6]
339 \f
340 RFC 3501                         IMAPv4                       March 2003
341
342
343    server sends a command continuation request response if it is ready
344    for the octets (if appropriate) and the remainder of the command.
345    This response is prefixed with the token "+".
346
347         Note: If instead, the server detected an error in the
348         command, it sends a BAD completion response with a tag
349         matching the command (as described below) to reject the
350         command and prevent the client from sending any more of the
351         command.
352
353         It is also possible for the server to send a completion
354         response for some other command (if multiple commands are
355         in progress), or untagged data.  In either case, the
356         command continuation request is still pending; the client
357         takes the appropriate action for the response, and reads
358         another response from the server.  In all cases, the client
359         MUST send a complete command (including receiving all
360         command continuation request responses and command
361         continuations for the command) before initiating a new
362         command.
363
364    The protocol receiver of an IMAP4rev1 server reads a command line
365    from the client, parses the command and its arguments, and transmits
366    server data and a server command completion result response.
367
368 2.2.2.  Server Protocol Sender and Client Protocol Receiver
369
370    Data transmitted by the server to the client and status responses
371    that do not indicate command completion are prefixed with the token
372    "*", and are called untagged responses.
373
374    Server data MAY be sent as a result of a client command, or MAY be
375    sent unilaterally by the server.  There is no syntactic difference
376    between server data that resulted from a specific command and server
377    data that were sent unilaterally.
378
379    The server completion result response indicates the success or
380    failure of the operation.  It is tagged with the same tag as the
381    client command which began the operation.  Thus, if more than one
382    command is in progress, the tag in a server completion response
383    identifies the command to which the response applies.  There are
384    three possible server completion responses: OK (indicating success),
385    NO (indicating failure), or BAD (indicating a protocol error such as
386    unrecognized command or command syntax error).
387
388    Servers SHOULD enforce the syntax outlined in this specification
389    strictly.  Any client command with a protocol syntax error, including
390    (but not limited to) missing or extraneous spaces or arguments,
391
392
393
394 Crispin                     Standards Track                     [Page 7]
395 \f
396 RFC 3501                         IMAPv4                       March 2003
397
398
399    SHOULD be rejected, and the client given a BAD server completion
400    response.
401
402    The protocol receiver of an IMAP4rev1 client reads a response line
403    from the server.  It then takes action on the response based upon the
404    first token of the response, which can be a tag, a "*", or a "+".
405
406    A client MUST be prepared to accept any server response at all times.
407    This includes server data that was not requested.  Server data SHOULD
408    be recorded, so that the client can reference its recorded copy
409    rather than sending a command to the server to request the data.  In
410    the case of certain server data, the data MUST be recorded.
411
412    This topic is discussed in greater detail in the Server Responses
413    section.
414
415 2.3.    Message Attributes
416
417    In addition to message text, each message has several attributes
418    associated with it.  These attributes can be retrieved individually
419    or in conjunction with other attributes or message texts.
420
421 2.3.1.  Message Numbers
422
423    Messages in IMAP4rev1 are accessed by one of two numbers; the unique
424    identifier or the message sequence number.
425
426
427 2.3.1.1.        Unique Identifier (UID) Message Attribute
428
429    A 32-bit value assigned to each message, which when used with the
430    unique identifier validity value (see below) forms a 64-bit value
431    that MUST NOT refer to any other message in the mailbox or any
432    subsequent mailbox with the same name forever.  Unique identifiers
433    are assigned in a strictly ascending fashion in the mailbox; as each
434    message is added to the mailbox it is assigned a higher UID than the
435    message(s) which were added previously.  Unlike message sequence
436    numbers, unique identifiers are not necessarily contiguous.
437
438    The unique identifier of a message MUST NOT change during the
439    session, and SHOULD NOT change between sessions.  Any change of
440    unique identifiers between sessions MUST be detectable using the
441    UIDVALIDITY mechanism discussed below.  Persistent unique identifiers
442    are required for a client to resynchronize its state from a previous
443    session with the server (e.g., disconnected or offline access
444    clients); this is discussed further in [IMAP-DISC].
445
446
447
448
449
450 Crispin                     Standards Track                     [Page 8]
451 \f
452 RFC 3501                         IMAPv4                       March 2003
453
454
455    Associated with every mailbox are two values which aid in unique
456    identifier handling: the next unique identifier value and the unique
457    identifier validity value.
458
459    The next unique identifier value is the predicted value that will be
460    assigned to a new message in the mailbox.  Unless the unique
461    identifier validity also changes (see below), the next unique
462    identifier value MUST have the following two characteristics.  First,
463    the next unique identifier value MUST NOT change unless new messages
464    are added to the mailbox; and second, the next unique identifier
465    value MUST change whenever new messages are added to the mailbox,
466    even if those new messages are subsequently expunged.
467
468         Note: The next unique identifier value is intended to
469         provide a means for a client to determine whether any
470         messages have been delivered to the mailbox since the
471         previous time it checked this value.  It is not intended to
472         provide any guarantee that any message will have this
473         unique identifier.  A client can only assume, at the time
474         that it obtains the next unique identifier value, that
475         messages arriving after that time will have a UID greater
476         than or equal to that value.
477
478    The unique identifier validity value is sent in a UIDVALIDITY
479    response code in an OK untagged response at mailbox selection time.
480    If unique identifiers from an earlier session fail to persist in this
481    session, the unique identifier validity value MUST be greater than
482    the one used in the earlier session.
483
484         Note: Ideally, unique identifiers SHOULD persist at all
485         times.  Although this specification recognizes that failure
486         to persist can be unavoidable in certain server
487         environments, it STRONGLY ENCOURAGES message store
488         implementation techniques that avoid this problem.  For
489         example:
490
491          1) Unique identifiers MUST be strictly ascending in the
492             mailbox at all times.  If the physical message store is
493             re-ordered by a non-IMAP agent, this requires that the
494             unique identifiers in the mailbox be regenerated, since
495             the former unique identifiers are no longer strictly
496             ascending as a result of the re-ordering.
497
498          2) If the message store has no mechanism to store unique
499             identifiers, it must regenerate unique identifiers at
500             each session, and each session must have a unique
501             UIDVALIDITY value.
502
503
504
505
506 Crispin                     Standards Track                     [Page 9]
507 \f
508 RFC 3501                         IMAPv4                       March 2003
509
510
511          3) If the mailbox is deleted and a new mailbox with the
512             same name is created at a later date, the server must
513             either keep track of unique identifiers from the
514             previous instance of the mailbox, or it must assign a
515             new UIDVALIDITY value to the new instance of the
516             mailbox.  A good UIDVALIDITY value to use in this case
517             is a 32-bit representation of the creation date/time of
518             the mailbox.  It is alright to use a constant such as
519             1, but only if it guaranteed that unique identifiers
520             will never be reused, even in the case of a mailbox
521             being deleted (or renamed) and a new mailbox by the
522             same name created at some future time.
523
524          4) The combination of mailbox name, UIDVALIDITY, and UID
525             must refer to a single immutable message on that server
526             forever.  In particular, the internal date, [RFC-2822]
527             size, envelope, body structure, and message texts
528             (RFC822, RFC822.HEADER, RFC822.TEXT, and all BODY[...]
529             fetch data items) must never change.  This does not
530             include message numbers, nor does it include attributes
531             that can be set by a STORE command (e.g., FLAGS).
532
533
534 2.3.1.2.        Message Sequence Number Message Attribute
535
536    A relative position from 1 to the number of messages in the mailbox.
537    This position MUST be ordered by ascending unique identifier.  As
538    each new message is added, it is assigned a message sequence number
539    that is 1 higher than the number of messages in the mailbox before
540    that new message was added.
541
542    Message sequence numbers can be reassigned during the session.  For
543    example, when a message is permanently removed (expunged) from the
544    mailbox, the message sequence number for all subsequent messages is
545    decremented.  The number of messages in the mailbox is also
546    decremented.  Similarly, a new message can be assigned a message
547    sequence number that was once held by some other message prior to an
548    expunge.
549
550    In addition to accessing messages by relative position in the
551    mailbox, message sequence numbers can be used in mathematical
552    calculations.  For example, if an untagged "11 EXISTS" is received,
553    and previously an untagged "8 EXISTS" was received, three new
554    messages have arrived with message sequence numbers of 9, 10, and 11.
555    Another example, if message 287 in a 523 message mailbox has UID
556    12345, there are exactly 286 messages which have lesser UIDs and 236
557    messages which have greater UIDs.
558
559
560
561
562 Crispin                     Standards Track                    [Page 10]
563 \f
564 RFC 3501                         IMAPv4                       March 2003
565
566
567 2.3.2.  Flags Message Attribute
568
569    A list of zero or more named tokens associated with the message.  A
570    flag is set by its addition to this list, and is cleared by its
571    removal.  There are two types of flags in IMAP4rev1.  A flag of
572    either type can be permanent or session-only.
573
574    A system flag is a flag name that is pre-defined in this
575    specification.  All system flags begin with "\".  Certain system
576    flags (\Deleted and \Seen) have special semantics described
577    elsewhere.  The currently-defined system flags are:
578
579         \Seen
580            Message has been read
581
582         \Answered
583            Message has been answered
584
585         \Flagged
586            Message is "flagged" for urgent/special attention
587
588         \Deleted
589            Message is "deleted" for removal by later EXPUNGE
590
591         \Draft
592            Message has not completed composition (marked as a draft).
593
594         \Recent
595            Message is "recently" arrived in this mailbox.  This session
596            is the first session to have been notified about this
597            message; if the session is read-write, subsequent sessions
598            will not see \Recent set for this message.  This flag can not
599            be altered by the client.
600
601            If it is not possible to determine whether or not this
602            session is the first session to be notified about a message,
603            then that message SHOULD be considered recent.
604
605            If multiple connections have the same mailbox selected
606            simultaneously, it is undefined which of these connections
607            will see newly-arrived messages with \Recent set and which
608            will see it without \Recent set.
609
610    A keyword is defined by the server implementation.  Keywords do not
611    begin with "\".  Servers MAY permit the client to define new keywords
612    in the mailbox (see the description of the PERMANENTFLAGS response
613    code for more information).
614
615
616
617
618 Crispin                     Standards Track                    [Page 11]
619 \f
620 RFC 3501                         IMAPv4                       March 2003
621
622
623    A flag can be permanent or session-only on a per-flag basis.
624    Permanent flags are those which the client can add or remove from the
625    message flags permanently; that is, concurrent and subsequent
626    sessions will see any change in permanent flags.  Changes to session
627    flags are valid only in that session.
628
629         Note: The \Recent system flag is a special case of a
630         session flag.  \Recent can not be used as an argument in a
631         STORE or APPEND command, and thus can not be changed at
632         all.
633
634 2.3.3.  Internal Date Message Attribute
635
636    The internal date and time of the message on the server.  This
637    is not the date and time in the [RFC-2822] header, but rather a
638    date and time which reflects when the message was received.  In
639    the case of messages delivered via [SMTP], this SHOULD be the
640    date and time of final delivery of the message as defined by
641    [SMTP].  In the case of messages delivered by the IMAP4rev1 COPY
642    command, this SHOULD be the internal date and time of the source
643    message.  In the case of messages delivered by the IMAP4rev1
644    APPEND command, this SHOULD be the date and time as specified in
645    the APPEND command description.  All other cases are
646    implementation defined.
647
648 2.3.4.  [RFC-2822] Size Message Attribute
649
650    The number of octets in the message, as expressed in [RFC-2822]
651    format.
652
653 2.3.5.  Envelope Structure Message Attribute
654
655    A parsed representation of the [RFC-2822] header of the message.
656    Note that the IMAP Envelope structure is not the same as an
657    [SMTP] envelope.
658
659 2.3.6.  Body Structure Message Attribute
660
661    A parsed representation of the [MIME-IMB] body structure
662    information of the message.
663
664
665
666
667
668
669
670
671
672
673
674 Crispin                     Standards Track                    [Page 12]
675 \f
676 RFC 3501                         IMAPv4                       March 2003
677
678
679 2.4.    Message Texts
680
681    In addition to being able to fetch the full [RFC-2822] text of a
682    message, IMAP4rev1 permits the fetching of portions of the full
683    message text.  Specifically, it is possible to fetch the
684    [RFC-2822] message header, [RFC-2822] message body, a [MIME-IMB]
685    body part, or a [MIME-IMB] header.
686
687 3.      State and Flow Diagram
688
689    Once the connection between client and server is established, an
690    IMAP4rev1 connection is in one of four states.  The initial
691    state is identified in the server greeting.  Most commands are
692    only valid in certain states.  It is a protocol error for the
693    client to attempt a command while the connection is in an
694    inappropriate state, and the server will respond with a BAD or
695    NO (depending upon server implementation) command completion
696    result.
697
698 3.1.    Not Authenticated State
699
700    In the not authenticated state, the client MUST supply
701    authentication credentials before most commands will be
702    permitted.  This state is entered when a connection starts
703    unless the connection has been pre-authenticated.
704
705 3.2.    Authenticated State
706
707    In the authenticated state, the client is authenticated and MUST
708    select a mailbox to access before commands that affect messages
709    will be permitted.  This state is entered when a
710    pre-authenticated connection starts, when acceptable
711    authentication credentials have been provided, after an error in
712    selecting a mailbox, or after a successful CLOSE command.
713
714 3.3.    Selected State
715
716    In a selected state, a mailbox has been selected to access.
717    This state is entered when a mailbox has been successfully
718    selected.
719
720
721
722
723
724
725
726
727
728
729
730 Crispin                     Standards Track                    [Page 13]
731 \f
732 RFC 3501                         IMAPv4                       March 2003
733
734
735 3.4.    Logout State
736
737    In the logout state, the connection is being terminated.  This
738    state can be entered as a result of a client request (via the
739    LOGOUT command) or by unilateral action on the part of either
740    the client or server.
741
742    If the client requests the logout state, the server MUST send an
743    untagged BYE response and a tagged OK response to the LOGOUT
744    command before the server closes the connection; and the client
745    MUST read the tagged OK response to the LOGOUT command before
746    the client closes the connection.
747
748    A server MUST NOT unilaterally close the connection without
749    sending an untagged BYE response that contains the reason for
750    having done so.  A client SHOULD NOT unilaterally close the
751    connection, and instead SHOULD issue a LOGOUT command.  If the
752    server detects that the client has unilaterally closed the
753    connection, the server MAY omit the untagged BYE response and
754    simply close its connection.
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786 Crispin                     Standards Track                    [Page 14]
787 \f
788 RFC 3501                         IMAPv4                       March 2003
789
790
791                    +----------------------+
792                    |connection established|
793                    +----------------------+
794                               ||
795                               \/
796             +--------------------------------------+
797             |          server greeting             |
798             +--------------------------------------+
799                       || (1)       || (2)        || (3)
800                       \/           ||            ||
801             +-----------------+    ||            ||
802             |Not Authenticated|    ||            ||
803             +-----------------+    ||            ||
804              || (7)   || (4)       ||            ||
805              ||       \/           \/            ||
806              ||     +----------------+           ||
807              ||     | Authenticated  |<=++       ||
808              ||     +----------------+  ||       ||
809              ||       || (7)   || (5)   || (6)   ||
810              ||       ||       \/       ||       ||
811              ||       ||    +--------+  ||       ||
812              ||       ||    |Selected|==++       ||
813              ||       ||    +--------+           ||
814              ||       ||       || (7)            ||
815              \/       \/       \/                \/
816             +--------------------------------------+
817             |               Logout                 |
818             +--------------------------------------+
819                               ||
820                               \/
821                 +-------------------------------+
822                 |both sides close the connection|
823                 +-------------------------------+
824
825          (1) connection without pre-authentication (OK greeting)
826          (2) pre-authenticated connection (PREAUTH greeting)
827          (3) rejected connection (BYE greeting)
828          (4) successful LOGIN or AUTHENTICATE command
829          (5) successful SELECT or EXAMINE command
830          (6) CLOSE command, or failed SELECT or EXAMINE command
831          (7) LOGOUT command, server shutdown, or connection closed
832
833
834
835
836
837
838
839
840
841
842 Crispin                     Standards Track                    [Page 15]
843 \f
844 RFC 3501                         IMAPv4                       March 2003
845
846
847 4.      Data Formats
848
849    IMAP4rev1 uses textual commands and responses.  Data in
850    IMAP4rev1 can be in one of several forms: atom, number, string,
851    parenthesized list, or NIL.  Note that a particular data item
852    may take more than one form; for example, a data item defined as
853    using "astring" syntax may be either an atom or a string.
854
855 4.1.    Atom
856
857    An atom consists of one or more non-special characters.
858
859 4.2.    Number
860
861    A number consists of one or more digit characters, and
862    represents a numeric value.
863
864 4.3.    String
865
866    A string is in one of two forms: either literal or quoted
867    string.  The literal form is the general form of string.  The
868    quoted string form is an alternative that avoids the overhead of
869    processing a literal at the cost of limitations of characters
870    which may be used.
871
872    A literal is a sequence of zero or more octets (including CR and
873    LF), prefix-quoted with an octet count in the form of an open
874    brace ("{"), the number of octets, close brace ("}"), and CRLF.
875    In the case of literals transmitted from server to client, the
876    CRLF is immediately followed by the octet data.  In the case of
877    literals transmitted from client to server, the client MUST wait
878    to receive a command continuation request (described later in
879    this document) before sending the octet data (and the remainder
880    of the command).
881
882    A quoted string is a sequence of zero or more 7-bit characters,
883    excluding CR and LF, with double quote (<">) characters at each
884    end.
885
886    The empty string is represented as either "" (a quoted string
887    with zero characters between double quotes) or as {0} followed
888    by CRLF (a literal with an octet count of 0).
889
890      Note: Even if the octet count is 0, a client transmitting a
891      literal MUST wait to receive a command continuation request.
892
893
894
895
896
897
898 Crispin                     Standards Track                    [Page 16]
899 \f
900 RFC 3501                         IMAPv4                       March 2003
901
902
903 4.3.1.  8-bit and Binary Strings
904
905    8-bit textual and binary mail is supported through the use of a
906    [MIME-IMB] content transfer encoding.  IMAP4rev1 implementations MAY
907    transmit 8-bit or multi-octet characters in literals, but SHOULD do
908    so only when the [CHARSET] is identified.
909
910    Although a BINARY body encoding is defined, unencoded binary strings
911    are not permitted.  A "binary string" is any string with NUL
912    characters.  Implementations MUST encode binary data into a textual
913    form, such as BASE64, before transmitting the data.  A string with an
914    excessive amount of CTL characters MAY also be considered to be
915    binary.
916
917 4.4.    Parenthesized List
918
919    Data structures are represented as a "parenthesized list"; a sequence
920    of data items, delimited by space, and bounded at each end by
921    parentheses.  A parenthesized list can contain other parenthesized
922    lists, using multiple levels of parentheses to indicate nesting.
923
924    The empty list is represented as () -- a parenthesized list with no
925    members.
926
927 4.5.    NIL
928
929    The special form "NIL" represents the non-existence of a particular
930    data item that is represented as a string or parenthesized list, as
931    distinct from the empty string "" or the empty parenthesized list ().
932
933         Note: NIL is never used for any data item which takes the
934         form of an atom.  For example, a mailbox name of "NIL" is a
935         mailbox named NIL as opposed to a non-existent mailbox
936         name.  This is because mailbox uses "astring" syntax which
937         is an atom or a string.  Conversely, an addr-name of NIL is
938         a non-existent personal name, because addr-name uses
939         "nstring" syntax which is NIL or a string, but never an
940         atom.
941
942
943
944
945
946
947
948
949
950
951
952
953
954 Crispin                     Standards Track                    [Page 17]
955 \f
956 RFC 3501                         IMAPv4                       March 2003
957
958
959 5.      Operational Considerations
960
961    The following rules are listed here to ensure that all IMAP4rev1
962    implementations interoperate properly.
963
964 5.1.    Mailbox Naming
965
966    Mailbox names are 7-bit.  Client implementations MUST NOT attempt to
967    create 8-bit mailbox names, and SHOULD interpret any 8-bit mailbox
968    names returned by LIST or LSUB as UTF-8.  Server implementations
969    SHOULD prohibit the creation of 8-bit mailbox names, and SHOULD NOT
970    return 8-bit mailbox names in LIST or LSUB.  See section 5.1.3 for
971    more information on how to represent non-ASCII mailbox names.
972
973         Note: 8-bit mailbox names were undefined in earlier
974         versions of this protocol.  Some sites used a local 8-bit
975         character set to represent non-ASCII mailbox names.  Such
976         usage is not interoperable, and is now formally deprecated.
977
978    The case-insensitive mailbox name INBOX is a special name reserved to
979    mean "the primary mailbox for this user on this server".  The
980    interpretation of all other names is implementation-dependent.
981
982    In particular, this specification takes no position on case
983    sensitivity in non-INBOX mailbox names.  Some server implementations
984    are fully case-sensitive; others preserve case of a newly-created
985    name but otherwise are case-insensitive; and yet others coerce names
986    to a particular case.  Client implementations MUST interact with any
987    of these.  If a server implementation interprets non-INBOX mailbox
988    names as case-insensitive, it MUST treat names using the
989    international naming convention specially as described in section
990    5.1.3.
991
992    There are certain client considerations when creating a new mailbox
993    name:
994
995    1)    Any character which is one of the atom-specials (see the Formal
996          Syntax) will require that the mailbox name be represented as a
997          quoted string or literal.
998
999    2)    CTL and other non-graphic characters are difficult to represent
1000          in a user interface and are best avoided.
1001
1002    3)    Although the list-wildcard characters ("%" and "*") are valid
1003          in a mailbox name, it is difficult to use such mailbox names
1004          with the LIST and LSUB commands due to the conflict with
1005          wildcard interpretation.
1006
1007
1008
1009
1010 Crispin                     Standards Track                    [Page 18]
1011 \f
1012 RFC 3501                         IMAPv4                       March 2003
1013
1014
1015    4)    Usually, a character (determined by the server implementation)
1016          is reserved to delimit levels of hierarchy.
1017
1018    5)    Two characters, "#" and "&", have meanings by convention, and
1019          should be avoided except when used in that convention.
1020
1021 5.1.1.  Mailbox Hierarchy Naming
1022
1023    If it is desired to export hierarchical mailbox names, mailbox names
1024    MUST be left-to-right hierarchical using a single character to
1025    separate levels of hierarchy.  The same hierarchy separator character
1026    is used for all levels of hierarchy within a single name.
1027
1028 5.1.2.  Mailbox Namespace Naming Convention
1029
1030    By convention, the first hierarchical element of any mailbox name
1031    which begins with "#" identifies the "namespace" of the remainder of
1032    the name.  This makes it possible to disambiguate between different
1033    types of mailbox stores, each of which have their own namespaces.
1034
1035         For example, implementations which offer access to USENET
1036         newsgroups MAY use the "#news" namespace to partition the
1037         USENET newsgroup namespace from that of other mailboxes.
1038         Thus, the comp.mail.misc newsgroup would have a mailbox
1039         name of "#news.comp.mail.misc", and the name
1040         "comp.mail.misc" can refer to a different object (e.g., a
1041         user's private mailbox).
1042
1043 5.1.3.  Mailbox International Naming Convention
1044
1045    By convention, international mailbox names in IMAP4rev1 are specified
1046    using a modified version of the UTF-7 encoding described in [UTF-7].
1047    Modified UTF-7 may also be usable in servers that implement an
1048    earlier version of this protocol.
1049
1050    In modified UTF-7, printable US-ASCII characters, except for "&",
1051    represent themselves; that is, characters with octet values 0x20-0x25
1052    and 0x27-0x7e.  The character "&" (0x26) is represented by the
1053    two-octet sequence "&-".
1054
1055    All other characters (octet values 0x00-0x1f and 0x7f-0xff) are
1056    represented in modified BASE64, with a further modification from
1057    [UTF-7] that "," is used instead of "/".  Modified BASE64 MUST NOT be
1058    used to represent any printing US-ASCII character which can represent
1059    itself.
1060
1061
1062
1063
1064
1065
1066 Crispin                     Standards Track                    [Page 19]
1067 \f
1068 RFC 3501                         IMAPv4                       March 2003
1069
1070
1071    "&" is used to shift to modified BASE64 and "-" to shift back to
1072    US-ASCII.  There is no implicit shift from BASE64 to US-ASCII, and
1073    null shifts ("-&" while in BASE64; note that "&-" while in US-ASCII
1074    means "&") are not permitted.  However, all names start in US-ASCII,
1075    and MUST end in US-ASCII; that is, a name that ends with a non-ASCII
1076    ISO-10646 character MUST end with a "-").
1077
1078    The purpose of these modifications is to correct the following
1079    problems with UTF-7:
1080
1081       1) UTF-7 uses the "+" character for shifting; this conflicts with
1082          the common use of "+" in mailbox names, in particular USENET
1083          newsgroup names.
1084
1085       2) UTF-7's encoding is BASE64 which uses the "/" character; this
1086          conflicts with the use of "/" as a popular hierarchy delimiter.
1087
1088       3) UTF-7 prohibits the unencoded usage of "\"; this conflicts with
1089          the use of "\" as a popular hierarchy delimiter.
1090
1091       4) UTF-7 prohibits the unencoded usage of "~"; this conflicts with
1092          the use of "~" in some servers as a home directory indicator.
1093
1094       5) UTF-7 permits multiple alternate forms to represent the same
1095          string; in particular, printable US-ASCII characters can be
1096          represented in encoded form.
1097
1098       Although modified UTF-7 is a convention, it establishes certain
1099       requirements on server handling of any mailbox name with an
1100       embedded "&" character.  In particular, server implementations
1101       MUST preserve the exact form of the modified BASE64 portion of a
1102       modified UTF-7 name and treat that text as case-sensitive, even if
1103       names are otherwise case-insensitive or case-folded.
1104
1105       Server implementations SHOULD verify that any mailbox name with an
1106       embedded "&" character, used as an argument to CREATE, is: in the
1107       correctly modified UTF-7 syntax, has no superfluous shifts, and
1108       has no encoding in modified BASE64 of any printing US-ASCII
1109       character which can represent itself.  However, client
1110       implementations MUST NOT depend upon the server doing this, and
1111       SHOULD NOT attempt to create a mailbox name with an embedded "&"
1112       character unless it complies with the modified UTF-7 syntax.
1113
1114       Server implementations which export a mail store that does not
1115       follow the modified UTF-7 convention MUST convert to modified
1116       UTF-7 any mailbox name that contains either non-ASCII characters
1117       or the "&" character.
1118
1119
1120
1121
1122 Crispin                     Standards Track                    [Page 20]
1123 \f
1124 RFC 3501                         IMAPv4                       March 2003
1125
1126
1127            For example, here is a mailbox name which mixes English,
1128            Chinese, and Japanese text:
1129            ~peter/mail/&U,BTFw-/&ZeVnLIqe-
1130
1131            For example, the string "&Jjo!" is not a valid mailbox
1132            name because it does not contain a shift to US-ASCII
1133            before the "!".  The correct form is "&Jjo-!".  The
1134            string "&U,BTFw-&ZeVnLIqe-" is not permitted because it
1135            contains a superfluous shift.  The correct form is
1136            "&U,BTF2XlZyyKng-".
1137
1138 5.2.    Mailbox Size and Message Status Updates
1139
1140    At any time, a server can send data that the client did not request.
1141    Sometimes, such behavior is REQUIRED.  For example, agents other than
1142    the server MAY add messages to the mailbox (e.g., new message
1143    delivery), change the flags of the messages in the mailbox (e.g.,
1144    simultaneous access to the same mailbox by multiple agents), or even
1145    remove messages from the mailbox.  A server MUST send mailbox size
1146    updates automatically if a mailbox size change is observed during the
1147    processing of a command.  A server SHOULD send message flag updates
1148    automatically, without requiring the client to request such updates
1149    explicitly.
1150
1151    Special rules exist for server notification of a client about the
1152    removal of messages to prevent synchronization errors; see the
1153    description of the EXPUNGE response for more detail.  In particular,
1154    it is NOT permitted to send an EXISTS response that would reduce the
1155    number of messages in the mailbox; only the EXPUNGE response can do
1156    this.
1157
1158    Regardless of what implementation decisions a client makes on
1159    remembering data from the server, a client implementation MUST record
1160    mailbox size updates.  It MUST NOT assume that any command after the
1161    initial mailbox selection will return the size of the mailbox.
1162
1163 5.3.    Response when no Command in Progress
1164
1165    Server implementations are permitted to send an untagged response
1166    (except for EXPUNGE) while there is no command in progress.  Server
1167    implementations that send such responses MUST deal with flow control
1168    considerations.  Specifically, they MUST either (1) verify that the
1169    size of the data does not exceed the underlying transport's available
1170    window size, or (2) use non-blocking writes.
1171
1172
1173
1174
1175
1176
1177
1178 Crispin                     Standards Track                    [Page 21]
1179 \f
1180 RFC 3501                         IMAPv4                       March 2003
1181
1182
1183 5.4.    Autologout Timer
1184
1185    If a server has an inactivity autologout timer, the duration of that
1186    timer MUST be at least 30 minutes.  The receipt of ANY command from
1187    the client during that interval SHOULD suffice to reset the
1188    autologout timer.
1189
1190 5.5.    Multiple Commands in Progress
1191
1192    The client MAY send another command without waiting for the
1193    completion result response of a command, subject to ambiguity rules
1194    (see below) and flow control constraints on the underlying data
1195    stream.  Similarly, a server MAY begin processing another command
1196    before processing the current command to completion, subject to
1197    ambiguity rules.  However, any command continuation request responses
1198    and command continuations MUST be negotiated before any subsequent
1199    command is initiated.
1200
1201    The exception is if an ambiguity would result because of a command
1202    that would affect the results of other commands.  Clients MUST NOT
1203    send multiple commands without waiting if an ambiguity would result.
1204    If the server detects a possible ambiguity, it MUST execute commands
1205    to completion in the order given by the client.
1206
1207    The most obvious example of ambiguity is when a command would affect
1208    the results of another command, e.g., a FETCH of a message's flags
1209    and a STORE of that same message's flags.
1210
1211    A non-obvious ambiguity occurs with commands that permit an untagged
1212    EXPUNGE response (commands other than FETCH, STORE, and SEARCH),
1213    since an untagged EXPUNGE response can invalidate sequence numbers in
1214    a subsequent command.  This is not a problem for FETCH, STORE, or
1215    SEARCH commands because servers are prohibited from sending EXPUNGE
1216    responses while any of those commands are in progress.  Therefore, if
1217    the client sends any command other than FETCH, STORE, or SEARCH, it
1218    MUST wait for the completion result response before sending a command
1219    with message sequence numbers.
1220
1221         Note: UID FETCH, UID STORE, and UID SEARCH are different
1222         commands from FETCH, STORE, and SEARCH.  If the client
1223         sends a UID command, it must wait for a completion result
1224         response before sending a command with message sequence
1225         numbers.
1226
1227
1228
1229
1230
1231
1232
1233
1234 Crispin                     Standards Track                    [Page 22]
1235 \f
1236 RFC 3501                         IMAPv4                       March 2003
1237
1238
1239    For example, the following non-waiting command sequences are invalid:
1240
1241       FETCH + NOOP + STORE
1242       STORE + COPY + FETCH
1243       COPY + COPY
1244       CHECK + FETCH
1245
1246    The following are examples of valid non-waiting command sequences:
1247
1248       FETCH + STORE + SEARCH + CHECK
1249       STORE + COPY + EXPUNGE
1250
1251       UID SEARCH + UID SEARCH may be valid or invalid as a non-waiting
1252       command sequence, depending upon whether or not the second UID
1253       SEARCH contains message sequence numbers.
1254
1255 6.      Client Commands
1256
1257    IMAP4rev1 commands are described in this section.  Commands are
1258    organized by the state in which the command is permitted.  Commands
1259    which are permitted in multiple states are listed in the minimum
1260    permitted state (for example, commands valid in authenticated and
1261    selected state are listed in the authenticated state commands).
1262
1263    Command arguments, identified by "Arguments:" in the command
1264    descriptions below, are described by function, not by syntax.  The
1265    precise syntax of command arguments is described in the Formal Syntax
1266    section.
1267
1268    Some commands cause specific server responses to be returned; these
1269    are identified by "Responses:" in the command descriptions below.
1270    See the response descriptions in the Responses section for
1271    information on these responses, and the Formal Syntax section for the
1272    precise syntax of these responses.  It is possible for server data to
1273    be transmitted as a result of any command.  Thus, commands that do
1274    not specifically require server data specify "no specific responses
1275    for this command" instead of "none".
1276
1277    The "Result:" in the command description refers to the possible
1278    tagged status responses to a command, and any special interpretation
1279    of these status responses.
1280
1281    The state of a connection is only changed by successful commands
1282    which are documented as changing state.  A rejected command (BAD
1283    response) never changes the state of the connection or of the
1284    selected mailbox.  A failed command (NO response) generally does not
1285    change the state of the connection or of the selected mailbox; the
1286    exception being the SELECT and EXAMINE commands.
1287
1288
1289
1290 Crispin                     Standards Track                    [Page 23]
1291 \f
1292 RFC 3501                         IMAPv4                       March 2003
1293
1294
1295 6.1.    Client Commands - Any State
1296
1297    The following commands are valid in any state: CAPABILITY, NOOP, and
1298    LOGOUT.
1299
1300 6.1.1.  CAPABILITY Command
1301
1302    Arguments:  none
1303
1304    Responses:  REQUIRED untagged response: CAPABILITY
1305
1306    Result:     OK - capability completed
1307                BAD - command unknown or arguments invalid
1308
1309       The CAPABILITY command requests a listing of capabilities that the
1310       server supports.  The server MUST send a single untagged
1311       CAPABILITY response with "IMAP4rev1" as one of the listed
1312       capabilities before the (tagged) OK response.
1313
1314       A capability name which begins with "AUTH=" indicates that the
1315       server supports that particular authentication mechanism.  All
1316       such names are, by definition, part of this specification.  For
1317       example, the authorization capability for an experimental
1318       "blurdybloop" authenticator would be "AUTH=XBLURDYBLOOP" and not
1319       "XAUTH=BLURDYBLOOP" or "XAUTH=XBLURDYBLOOP".
1320
1321       Other capability names refer to extensions, revisions, or
1322       amendments to this specification.  See the documentation of the
1323       CAPABILITY response for additional information.  No capabilities,
1324       beyond the base IMAP4rev1 set defined in this specification, are
1325       enabled without explicit client action to invoke the capability.
1326
1327       Client and server implementations MUST implement the STARTTLS,
1328       LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS])
1329       capabilities.  See the Security Considerations section for
1330       important information.
1331
1332       See the section entitled "Client Commands -
1333       Experimental/Expansion" for information about the form of site or
1334       implementation-specific capabilities.
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346 Crispin                     Standards Track                    [Page 24]
1347 \f
1348 RFC 3501                         IMAPv4                       March 2003
1349
1350
1351    Example:    C: abcd CAPABILITY
1352                S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI
1353                LOGINDISABLED
1354                S: abcd OK CAPABILITY completed
1355                C: efgh STARTTLS
1356                S: efgh OK STARTLS completed
1357                <TLS negotiation, further commands are under [TLS] layer>
1358                C: ijkl CAPABILITY
1359                S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI AUTH=PLAIN
1360                S: ijkl OK CAPABILITY completed
1361
1362
1363 6.1.2.  NOOP Command
1364
1365    Arguments:  none
1366
1367    Responses:  no specific responses for this command (but see below)
1368
1369    Result:     OK - noop completed
1370                BAD - command unknown or arguments invalid
1371
1372       The NOOP command always succeeds.  It does nothing.
1373
1374       Since any command can return a status update as untagged data, the
1375       NOOP command can be used as a periodic poll for new messages or
1376       message status updates during a period of inactivity (this is the
1377       preferred method to do this).  The NOOP command can also be used
1378       to reset any inactivity autologout timer on the server.
1379
1380    Example:    C: a002 NOOP
1381                S: a002 OK NOOP completed
1382                   . . .
1383                C: a047 NOOP
1384                S: * 22 EXPUNGE
1385                S: * 23 EXISTS
1386                S: * 3 RECENT
1387                S: * 14 FETCH (FLAGS (\Seen \Deleted))
1388                S: a047 OK NOOP completed
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402 Crispin                     Standards Track                    [Page 25]
1403 \f
1404 RFC 3501                         IMAPv4                       March 2003
1405
1406
1407 6.1.3.  LOGOUT Command
1408
1409    Arguments:  none
1410
1411    Responses:  REQUIRED untagged response: BYE
1412
1413    Result:     OK - logout completed
1414                BAD - command unknown or arguments invalid
1415
1416       The LOGOUT command informs the server that the client is done with
1417       the connection.  The server MUST send a BYE untagged response
1418       before the (tagged) OK response, and then close the network
1419       connection.
1420
1421    Example:    C: A023 LOGOUT
1422                S: * BYE IMAP4rev1 Server logging out
1423                S: A023 OK LOGOUT completed
1424                (Server and client then close the connection)
1425
1426 6.2.    Client Commands - Not Authenticated State
1427
1428    In the not authenticated state, the AUTHENTICATE or LOGIN command
1429    establishes authentication and enters the authenticated state.  The
1430    AUTHENTICATE command provides a general mechanism for a variety of
1431    authentication techniques, privacy protection, and integrity
1432    checking; whereas the LOGIN command uses a traditional user name and
1433    plaintext password pair and has no means of establishing privacy
1434    protection or integrity checking.
1435
1436    The STARTTLS command is an alternate form of establishing session
1437    privacy protection and integrity checking, but does not establish
1438    authentication or enter the authenticated state.
1439
1440    Server implementations MAY allow access to certain mailboxes without
1441    establishing authentication.  This can be done by means of the
1442    ANONYMOUS [SASL] authenticator described in [ANONYMOUS].  An older
1443    convention is a LOGIN command using the userid "anonymous"; in this
1444    case, a password is required although the server may choose to accept
1445    any password.  The restrictions placed on anonymous users are
1446    implementation-dependent.
1447
1448    Once authenticated (including as anonymous), it is not possible to
1449    re-enter not authenticated state.
1450
1451
1452
1453
1454
1455
1456
1457
1458 Crispin                     Standards Track                    [Page 26]
1459 \f
1460 RFC 3501                         IMAPv4                       March 2003
1461
1462
1463    In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
1464    the following commands are valid in the not authenticated state:
1465    STARTTLS, AUTHENTICATE and LOGIN.  See the Security Considerations
1466    section for important information about these commands.
1467
1468 6.2.1.  STARTTLS Command
1469
1470    Arguments:  none
1471
1472    Responses:  no specific response for this command
1473
1474    Result:     OK - starttls completed, begin TLS negotiation
1475                BAD - command unknown or arguments invalid
1476
1477       A [TLS] negotiation begins immediately after the CRLF at the end
1478       of the tagged OK response from the server.  Once a client issues a
1479       STARTTLS command, it MUST NOT issue further commands until a
1480       server response is seen and the [TLS] negotiation is complete.
1481
1482       The server remains in the non-authenticated state, even if client
1483       credentials are supplied during the [TLS] negotiation.  This does
1484       not preclude an authentication mechanism such as EXTERNAL (defined
1485       in [SASL]) from using client identity determined by the [TLS]
1486       negotiation.
1487
1488       Once [TLS] has been started, the client MUST discard cached
1489       information about server capabilities and SHOULD re-issue the
1490       CAPABILITY command.  This is necessary to protect against man-in-
1491       the-middle attacks which alter the capabilities list prior to
1492       STARTTLS.  The server MAY advertise different capabilities after
1493       STARTTLS.
1494
1495    Example:    C: a001 CAPABILITY
1496                S: * CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED
1497                S: a001 OK CAPABILITY completed
1498                C: a002 STARTTLS
1499                S: a002 OK Begin TLS negotiation now
1500                <TLS negotiation, further commands are under [TLS] layer>
1501                C: a003 CAPABILITY
1502                S: * CAPABILITY IMAP4rev1 AUTH=PLAIN
1503                S: a003 OK CAPABILITY completed
1504                C: a004 LOGIN joe password
1505                S: a004 OK LOGIN completed
1506
1507
1508
1509
1510
1511
1512
1513
1514 Crispin                     Standards Track                    [Page 27]
1515 \f
1516 RFC 3501                         IMAPv4                       March 2003
1517
1518
1519 6.2.2.  AUTHENTICATE Command
1520
1521    Arguments:  authentication mechanism name
1522
1523    Responses:  continuation data can be requested
1524
1525    Result:     OK - authenticate completed, now in authenticated state
1526                NO - authenticate failure: unsupported authentication
1527                     mechanism, credentials rejected
1528                BAD - command unknown or arguments invalid,
1529                     authentication exchange cancelled
1530
1531       The AUTHENTICATE command indicates a [SASL] authentication
1532       mechanism to the server.  If the server supports the requested
1533       authentication mechanism, it performs an authentication protocol
1534       exchange to authenticate and identify the client.  It MAY also
1535       negotiate an OPTIONAL security layer for subsequent protocol
1536       interactions.  If the requested authentication mechanism is not
1537       supported, the server SHOULD reject the AUTHENTICATE command by
1538       sending a tagged NO response.
1539
1540       The AUTHENTICATE command does not support the optional "initial
1541       response" feature of [SASL].  Section 5.1 of [SASL] specifies how
1542       to handle an authentication mechanism which uses an initial
1543       response.
1544
1545       The service name specified by this protocol's profile of [SASL] is
1546       "imap".
1547
1548       The authentication protocol exchange consists of a series of
1549       server challenges and client responses that are specific to the
1550       authentication mechanism.  A server challenge consists of a
1551       command continuation request response with the "+" token followed
1552       by a BASE64 encoded string.  The client response consists of a
1553       single line consisting of a BASE64 encoded string.  If the client
1554       wishes to cancel an authentication exchange, it issues a line
1555       consisting of a single "*".  If the server receives such a
1556       response, it MUST reject the AUTHENTICATE command by sending a
1557       tagged BAD response.
1558
1559       If a security layer is negotiated through the [SASL]
1560       authentication exchange, it takes effect immediately following the
1561       CRLF that concludes the authentication exchange for the client,
1562       and the CRLF of the tagged OK response for the server.
1563
1564       While client and server implementations MUST implement the
1565       AUTHENTICATE command itself, it is not required to implement any
1566       authentication mechanisms other than the PLAIN mechanism described
1567
1568
1569
1570 Crispin                     Standards Track                    [Page 28]
1571 \f
1572 RFC 3501                         IMAPv4                       March 2003
1573
1574
1575       in [IMAP-TLS].  Also, an authentication mechanism is not required
1576       to support any security layers.
1577
1578            Note: a server implementation MUST implement a
1579            configuration in which it does NOT permit any plaintext
1580            password mechanisms, unless either the STARTTLS command
1581            has been negotiated or some other mechanism that
1582            protects the session from password snooping has been
1583            provided.  Server sites SHOULD NOT use any configuration
1584            which permits a plaintext password mechanism without
1585            such a protection mechanism against password snooping.
1586            Client and server implementations SHOULD implement
1587            additional [SASL] mechanisms that do not use plaintext
1588            passwords, such the GSSAPI mechanism described in [SASL]
1589            and/or the [DIGEST-MD5] mechanism.
1590
1591       Servers and clients can support multiple authentication
1592       mechanisms.  The server SHOULD list its supported authentication
1593       mechanisms in the response to the CAPABILITY command so that the
1594       client knows which authentication mechanisms to use.
1595
1596       A server MAY include a CAPABILITY response code in the tagged OK
1597       response of a successful AUTHENTICATE command in order to send
1598       capabilities automatically.  It is unnecessary for a client to
1599       send a separate CAPABILITY command if it recognizes these
1600       automatic capabilities.  This should only be done if a security
1601       layer was not negotiated by the AUTHENTICATE command, because the
1602       tagged OK response as part of an AUTHENTICATE command is not
1603       protected by encryption/integrity checking.  [SASL] requires the
1604       client to re-issue a CAPABILITY command in this case.
1605
1606       If an AUTHENTICATE command fails with a NO response, the client
1607       MAY try another authentication mechanism by issuing another
1608       AUTHENTICATE command.  It MAY also attempt to authenticate by
1609       using the LOGIN command (see section 6.2.3 for more detail).  In
1610       other words, the client MAY request authentication types in
1611       decreasing order of preference, with the LOGIN command as a last
1612       resort.
1613
1614       The authorization identity passed from the client to the server
1615       during the authentication exchange is interpreted by the server as
1616       the user name whose privileges the client is requesting.
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626 Crispin                     Standards Track                    [Page 29]
1627 \f
1628 RFC 3501                         IMAPv4                       March 2003
1629
1630
1631    Example:    S: * OK IMAP4rev1 Server
1632                C: A001 AUTHENTICATE GSSAPI
1633                S: +
1634                C: YIIB+wYJKoZIhvcSAQICAQBuggHqMIIB5qADAgEFoQMCAQ6iBw
1635                   MFACAAAACjggEmYYIBIjCCAR6gAwIBBaESGxB1Lndhc2hpbmd0
1636                   b24uZWR1oi0wK6ADAgEDoSQwIhsEaW1hcBsac2hpdmFtcy5jYW
1637                   Mud2FzaGluZ3Rvbi5lZHWjgdMwgdCgAwIBAaEDAgEDooHDBIHA
1638                   cS1GSa5b+fXnPZNmXB9SjL8Ollj2SKyb+3S0iXMljen/jNkpJX
1639                   AleKTz6BQPzj8duz8EtoOuNfKgweViyn/9B9bccy1uuAE2HI0y
1640                   C/PHXNNU9ZrBziJ8Lm0tTNc98kUpjXnHZhsMcz5Mx2GR6dGknb
1641                   I0iaGcRerMUsWOuBmKKKRmVMMdR9T3EZdpqsBd7jZCNMWotjhi
1642                   vd5zovQlFqQ2Wjc2+y46vKP/iXxWIuQJuDiisyXF0Y8+5GTpAL
1643                   pHDc1/pIGmMIGjoAMCAQGigZsEgZg2on5mSuxoDHEA1w9bcW9n
1644                   FdFxDKpdrQhVGVRDIzcCMCTzvUboqb5KjY1NJKJsfjRQiBYBdE
1645                   NKfzK+g5DlV8nrw81uOcP8NOQCLR5XkoMHC0Dr/80ziQzbNqhx
1646                   O6652Npft0LQwJvenwDI13YxpwOdMXzkWZN/XrEqOWp6GCgXTB
1647                   vCyLWLlWnbaUkZdEYbKHBPjd8t/1x5Yg==
1648                S: + YGgGCSqGSIb3EgECAgIAb1kwV6ADAgEFoQMCAQ+iSzBJoAMC
1649                   AQGiQgRAtHTEuOP2BXb9sBYFR4SJlDZxmg39IxmRBOhXRKdDA0
1650                   uHTCOT9Bq3OsUTXUlk0CsFLoa8j+gvGDlgHuqzWHPSQg==
1651                C:
1652                S: + YDMGCSqGSIb3EgECAgIBAAD/////6jcyG4GE3KkTzBeBiVHe
1653                   ceP2CWY0SR0fAQAgAAQEBAQ=
1654                C: YDMGCSqGSIb3EgECAgIBAAD/////3LQBHXTpFfZgrejpLlLImP
1655                   wkhbfa2QteAQAgAG1yYwE=
1656                S: A001 OK GSSAPI authentication successful
1657
1658         Note: The line breaks within server challenges and client
1659         responses are for editorial clarity and are not in real
1660         authenticators.
1661
1662
1663 6.2.3.  LOGIN Command
1664
1665    Arguments:  user name
1666                password
1667
1668    Responses:  no specific responses for this command
1669
1670    Result:     OK - login completed, now in authenticated state
1671                NO - login failure: user name or password rejected
1672                BAD - command unknown or arguments invalid
1673
1674       The LOGIN command identifies the client to the server and carries
1675       the plaintext password authenticating this user.
1676
1677
1678
1679
1680
1681
1682 Crispin                     Standards Track                    [Page 30]
1683 \f
1684 RFC 3501                         IMAPv4                       March 2003
1685
1686
1687       A server MAY include a CAPABILITY response code in the tagged OK
1688       response to a successful LOGIN command in order to send
1689       capabilities automatically.  It is unnecessary for a client to
1690       send a separate CAPABILITY command if it recognizes these
1691       automatic capabilities.
1692
1693    Example:    C: a001 LOGIN SMITH SESAME
1694                S: a001 OK LOGIN completed
1695
1696         Note: Use of the LOGIN command over an insecure network
1697         (such as the Internet) is a security risk, because anyone
1698         monitoring network traffic can obtain plaintext passwords.
1699         The LOGIN command SHOULD NOT be used except as a last
1700         resort, and it is recommended that client implementations
1701         have a means to disable any automatic use of the LOGIN
1702         command.
1703
1704         Unless either the STARTTLS command has been negotiated or
1705         some other mechanism that protects the session from
1706         password snooping has been provided, a server
1707         implementation MUST implement a configuration in which it
1708         advertises the LOGINDISABLED capability and does NOT permit
1709         the LOGIN command.  Server sites SHOULD NOT use any
1710         configuration which permits the LOGIN command without such
1711         a protection mechanism against password snooping.  A client
1712         implementation MUST NOT send a LOGIN command if the
1713         LOGINDISABLED capability is advertised.
1714
1715 6.3.    Client Commands - Authenticated State
1716
1717    In the authenticated state, commands that manipulate mailboxes as
1718    atomic entities are permitted.  Of these commands, the SELECT and
1719    EXAMINE commands will select a mailbox for access and enter the
1720    selected state.
1721
1722    In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
1723    the following commands are valid in the authenticated state: SELECT,
1724    EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB,
1725    STATUS, and APPEND.
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738 Crispin                     Standards Track                    [Page 31]
1739 \f
1740 RFC 3501                         IMAPv4                       March 2003
1741
1742
1743 6.3.1.  SELECT Command
1744
1745    Arguments:  mailbox name
1746
1747    Responses:  REQUIRED untagged responses: FLAGS, EXISTS, RECENT
1748                REQUIRED OK untagged responses:  UNSEEN,  PERMANENTFLAGS,
1749                UIDNEXT, UIDVALIDITY
1750
1751    Result:     OK - select completed, now in selected state
1752                NO - select failure, now in authenticated state: no
1753                     such mailbox, can't access mailbox
1754                BAD - command unknown or arguments invalid
1755
1756       The SELECT command selects a mailbox so that messages in the
1757       mailbox can be accessed.  Before returning an OK to the client,
1758       the server MUST send the following untagged data to the client.
1759       Note that earlier versions of this protocol only required the
1760       FLAGS, EXISTS, and RECENT untagged data; consequently, client
1761       implementations SHOULD implement default behavior for missing data
1762       as discussed with the individual item.
1763
1764          FLAGS       Defined flags in the mailbox.  See the description
1765                      of the FLAGS response for more detail.
1766
1767          <n> EXISTS  The number of messages in the mailbox.  See the
1768                      description of the EXISTS response for more detail.
1769
1770          <n> RECENT  The number of messages with the \Recent flag set.
1771                      See the description of the RECENT response for more
1772                      detail.
1773
1774          OK [UNSEEN <n>]
1775                      The message sequence number of the first unseen
1776                      message in the mailbox.  If this is missing, the
1777                      client can not make any assumptions about the first
1778                      unseen message in the mailbox, and needs to issue a
1779                      SEARCH command if it wants to find it.
1780
1781          OK [PERMANENTFLAGS (<list of flags>)]
1782                      A list of message flags that the client can change
1783                      permanently.  If this is missing, the client should
1784                      assume that all flags can be changed permanently.
1785
1786          OK [UIDNEXT <n>]
1787                      The next unique identifier value.  Refer to section
1788                      2.3.1.1 for more information.  If this is missing,
1789                      the client can not make any assumptions about the
1790                      next unique identifier value.
1791
1792
1793
1794 Crispin                     Standards Track                    [Page 32]
1795 \f
1796 RFC 3501                         IMAPv4                       March 2003
1797
1798
1799          OK [UIDVALIDITY <n>]
1800                      The unique identifier validity value.  Refer to
1801                      section 2.3.1.1 for more information.  If this is
1802                      missing, the server does not support unique
1803                      identifiers.
1804
1805       Only one mailbox can be selected at a time in a connection;
1806       simultaneous access to multiple mailboxes requires multiple
1807       connections.  The SELECT command automatically deselects any
1808       currently selected mailbox before attempting the new selection.
1809       Consequently, if a mailbox is selected and a SELECT command that
1810       fails is attempted, no mailbox is selected.
1811
1812       If the client is permitted to modify the mailbox, the server
1813       SHOULD prefix the text of the tagged OK response with the
1814       "[READ-WRITE]" response code.
1815
1816       If the client is not permitted to modify the mailbox but is
1817       permitted read access, the mailbox is selected as read-only, and
1818       the server MUST prefix the text of the tagged OK response to
1819       SELECT with the "[READ-ONLY]" response code.  Read-only access
1820       through SELECT differs from the EXAMINE command in that certain
1821       read-only mailboxes MAY permit the change of permanent state on a
1822       per-user (as opposed to global) basis.  Netnews messages marked in
1823       a server-based .newsrc file are an example of such per-user
1824       permanent state that can be modified with read-only mailboxes.
1825
1826    Example:    C: A142 SELECT INBOX
1827                S: * 172 EXISTS
1828                S: * 1 RECENT
1829                S: * OK [UNSEEN 12] Message 12 is first unseen
1830                S: * OK [UIDVALIDITY 3857529045] UIDs valid
1831                S: * OK [UIDNEXT 4392] Predicted next UID
1832                S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
1833                S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
1834                S: A142 OK [READ-WRITE] SELECT completed
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850 Crispin                     Standards Track                    [Page 33]
1851 \f
1852 RFC 3501                         IMAPv4                       March 2003
1853
1854
1855 6.3.2.  EXAMINE Command
1856
1857    Arguments:  mailbox name
1858
1859    Responses:  REQUIRED untagged responses: FLAGS, EXISTS, RECENT
1860                REQUIRED OK untagged responses:  UNSEEN,  PERMANENTFLAGS,
1861                UIDNEXT, UIDVALIDITY
1862
1863    Result:     OK - examine completed, now in selected state
1864                NO - examine failure, now in authenticated state: no
1865                     such mailbox, can't access mailbox
1866                BAD - command unknown or arguments invalid
1867
1868       The EXAMINE command is identical to SELECT and returns the same
1869       output; however, the selected mailbox is identified as read-only.
1870       No changes to the permanent state of the mailbox, including
1871       per-user state, are permitted; in particular, EXAMINE MUST NOT
1872       cause messages to lose the \Recent flag.
1873
1874       The text of the tagged OK response to the EXAMINE command MUST
1875       begin with the "[READ-ONLY]" response code.
1876
1877    Example:    C: A932 EXAMINE blurdybloop
1878                S: * 17 EXISTS
1879                S: * 2 RECENT
1880                S: * OK [UNSEEN 8] Message 8 is first unseen
1881                S: * OK [UIDVALIDITY 3857529045] UIDs valid
1882                S: * OK [UIDNEXT 4392] Predicted next UID
1883                S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
1884                S: * OK [PERMANENTFLAGS ()] No permanent flags permitted
1885                S: A932 OK [READ-ONLY] EXAMINE completed
1886
1887
1888 6.3.3.  CREATE Command
1889
1890    Arguments:  mailbox name
1891
1892    Responses:  no specific responses for this command
1893
1894    Result:     OK - create completed
1895                NO - create failure: can't create mailbox with that name
1896                BAD - command unknown or arguments invalid
1897
1898       The CREATE command creates a mailbox with the given name.  An OK
1899       response is returned only if a new mailbox with that name has been
1900       created.  It is an error to attempt to create INBOX or a mailbox
1901       with a name that refers to an extant mailbox.  Any error in
1902       creation will return a tagged NO response.
1903
1904
1905
1906 Crispin                     Standards Track                    [Page 34]
1907 \f
1908 RFC 3501                         IMAPv4                       March 2003
1909
1910
1911       If the mailbox name is suffixed with the server's hierarchy
1912       separator character (as returned from the server by a LIST
1913       command), this is a declaration that the client intends to create
1914       mailbox names under this name in the hierarchy.  Server
1915       implementations that do not require this declaration MUST ignore
1916       the declaration.  In any case, the name created is without the
1917       trailing hierarchy delimiter.
1918
1919       If the server's hierarchy separator character appears elsewhere in
1920       the name, the server SHOULD create any superior hierarchical names
1921       that are needed for the CREATE command to be successfully
1922       completed.  In other words, an attempt to create "foo/bar/zap" on
1923       a server in which "/" is the hierarchy separator character SHOULD
1924       create foo/ and foo/bar/ if they do not already exist.
1925
1926       If a new mailbox is created with the same name as a mailbox which
1927       was deleted, its unique identifiers MUST be greater than any
1928       unique identifiers used in the previous incarnation of the mailbox
1929       UNLESS the new incarnation has a different unique identifier
1930       validity value.  See the description of the UID command for more
1931       detail.
1932
1933    Example:    C: A003 CREATE owatagusiam/
1934                S: A003 OK CREATE completed
1935                C: A004 CREATE owatagusiam/blurdybloop
1936                S: A004 OK CREATE completed
1937
1938         Note: The interpretation of this example depends on whether
1939         "/" was returned as the hierarchy separator from LIST.  If
1940         "/" is the hierarchy separator, a new level of hierarchy
1941         named "owatagusiam" with a member called "blurdybloop" is
1942         created.  Otherwise, two mailboxes at the same hierarchy
1943         level are created.
1944
1945
1946 6.3.4.  DELETE Command
1947
1948    Arguments:  mailbox name
1949
1950    Responses:  no specific responses for this command
1951
1952    Result:     OK - delete completed
1953                NO - delete failure: can't delete mailbox with that name
1954                BAD - command unknown or arguments invalid
1955
1956
1957
1958
1959
1960
1961
1962 Crispin                     Standards Track                    [Page 35]
1963 \f
1964 RFC 3501                         IMAPv4                       March 2003
1965
1966
1967       The DELETE command permanently removes the mailbox with the given
1968       name.  A tagged OK response is returned only if the mailbox has
1969       been deleted.  It is an error to attempt to delete INBOX or a
1970       mailbox name that does not exist.
1971
1972       The DELETE command MUST NOT remove inferior hierarchical names.
1973       For example, if a mailbox "foo" has an inferior "foo.bar"
1974       (assuming "." is the hierarchy delimiter character), removing
1975       "foo" MUST NOT remove "foo.bar".  It is an error to attempt to
1976       delete a name that has inferior hierarchical names and also has
1977       the \Noselect mailbox name attribute (see the description of the
1978       LIST response for more details).
1979
1980       It is permitted to delete a name that has inferior hierarchical
1981       names and does not have the \Noselect mailbox name attribute.  In
1982       this case, all messages in that mailbox are removed, and the name
1983       will acquire the \Noselect mailbox name attribute.
1984
1985       The value of the highest-used unique identifier of the deleted
1986       mailbox MUST be preserved so that a new mailbox created with the
1987       same name will not reuse the identifiers of the former
1988       incarnation, UNLESS the new incarnation has a different unique
1989       identifier validity value.  See the description of the UID command
1990       for more detail.
1991
1992    Examples:   C: A682 LIST "" *
1993                S: * LIST () "/" blurdybloop
1994                S: * LIST (\Noselect) "/" foo
1995                S: * LIST () "/" foo/bar
1996                S: A682 OK LIST completed
1997                C: A683 DELETE blurdybloop
1998                S: A683 OK DELETE completed
1999                C: A684 DELETE foo
2000                S: A684 NO Name "foo" has inferior hierarchical names
2001                C: A685 DELETE foo/bar
2002                S: A685 OK DELETE Completed
2003                C: A686 LIST "" *
2004                S: * LIST (\Noselect) "/" foo
2005                S: A686 OK LIST completed
2006                C: A687 DELETE foo
2007                S: A687 OK DELETE Completed
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018 Crispin                     Standards Track                    [Page 36]
2019 \f
2020 RFC 3501                         IMAPv4                       March 2003
2021
2022
2023                C: A82 LIST "" *
2024                S: * LIST () "." blurdybloop
2025                S: * LIST () "." foo
2026                S: * LIST () "." foo.bar
2027                S: A82 OK LIST completed
2028                C: A83 DELETE blurdybloop
2029                S: A83 OK DELETE completed
2030                C: A84 DELETE foo
2031                S: A84 OK DELETE Completed
2032                C: A85 LIST "" *
2033                S: * LIST () "." foo.bar
2034                S: A85 OK LIST completed
2035                C: A86 LIST "" %
2036                S: * LIST (\Noselect) "." foo
2037                S: A86 OK LIST completed
2038
2039
2040 6.3.5.  RENAME Command
2041
2042    Arguments:  existing mailbox name
2043                new mailbox name
2044
2045    Responses:  no specific responses for this command
2046
2047    Result:     OK - rename completed
2048                NO - rename failure: can't rename mailbox with that name,
2049                     can't rename to mailbox with that name
2050                BAD - command unknown or arguments invalid
2051
2052       The RENAME command changes the name of a mailbox.  A tagged OK
2053       response is returned only if the mailbox has been renamed.  It is
2054       an error to attempt to rename from a mailbox name that does not
2055       exist or to a mailbox name that already exists.  Any error in
2056       renaming will return a tagged NO response.
2057
2058       If the name has inferior hierarchical names, then the inferior
2059       hierarchical names MUST also be renamed.  For example, a rename of
2060       "foo" to "zap" will rename "foo/bar" (assuming "/" is the
2061       hierarchy delimiter character) to "zap/bar".
2062
2063       If the server's hierarchy separator character appears in the name,
2064       the server SHOULD create any superior hierarchical names that are
2065       needed for the RENAME command to complete successfully.  In other
2066       words, an attempt to rename "foo/bar/zap" to baz/rag/zowie on a
2067       server in which "/" is the hierarchy separator character SHOULD
2068       create baz/ and baz/rag/ if they do not already exist.
2069
2070
2071
2072
2073
2074 Crispin                     Standards Track                    [Page 37]
2075 \f
2076 RFC 3501                         IMAPv4                       March 2003
2077
2078
2079       The value of the highest-used unique identifier of the old mailbox
2080       name MUST be preserved so that a new mailbox created with the same
2081       name will not reuse the identifiers of the former incarnation,
2082       UNLESS the new incarnation has a different unique identifier
2083       validity value.  See the description of the UID command for more
2084       detail.
2085
2086       Renaming INBOX is permitted, and has special behavior.  It moves
2087       all messages in INBOX to a new mailbox with the given name,
2088       leaving INBOX empty.  If the server implementation supports
2089       inferior hierarchical names of INBOX, these are unaffected by a
2090       rename of INBOX.
2091
2092    Examples:   C: A682 LIST "" *
2093                S: * LIST () "/" blurdybloop
2094                S: * LIST (\Noselect) "/" foo
2095                S: * LIST () "/" foo/bar
2096                S: A682 OK LIST completed
2097                C: A683 RENAME blurdybloop sarasoop
2098                S: A683 OK RENAME completed
2099                C: A684 RENAME foo zowie
2100                S: A684 OK RENAME Completed
2101                C: A685 LIST "" *
2102                S: * LIST () "/" sarasoop
2103                S: * LIST (\Noselect) "/" zowie
2104                S: * LIST () "/" zowie/bar
2105                S: A685 OK LIST completed
2106
2107                C: Z432 LIST "" *
2108                S: * LIST () "." INBOX
2109                S: * LIST () "." INBOX.bar
2110                S: Z432 OK LIST completed
2111                C: Z433 RENAME INBOX old-mail
2112                S: Z433 OK RENAME completed
2113                C: Z434 LIST "" *
2114                S: * LIST () "." INBOX
2115                S: * LIST () "." INBOX.bar
2116                S: * LIST () "." old-mail
2117                S: Z434 OK LIST completed
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130 Crispin                     Standards Track                    [Page 38]
2131 \f
2132 RFC 3501                         IMAPv4                       March 2003
2133
2134
2135 6.3.6.  SUBSCRIBE Command
2136
2137    Arguments:  mailbox
2138
2139    Responses:  no specific responses for this command
2140
2141    Result:     OK - subscribe completed
2142                NO - subscribe failure: can't subscribe to that name
2143                BAD - command unknown or arguments invalid
2144
2145       The SUBSCRIBE command adds the specified mailbox name to the
2146       server's set of "active" or "subscribed" mailboxes as returned by
2147       the LSUB command.  This command returns a tagged OK response only
2148       if the subscription is successful.
2149
2150       A server MAY validate the mailbox argument to SUBSCRIBE to verify
2151       that it exists.  However, it MUST NOT unilaterally remove an
2152       existing mailbox name from the subscription list even if a mailbox
2153       by that name no longer exists.
2154
2155            Note: This requirement is because a server site can
2156            choose to routinely remove a mailbox with a well-known
2157            name (e.g., "system-alerts") after its contents expire,
2158            with the intention of recreating it when new contents
2159            are appropriate.
2160
2161
2162    Example:    C: A002 SUBSCRIBE #news.comp.mail.mime
2163                S: A002 OK SUBSCRIBE completed
2164
2165
2166 6.3.7.  UNSUBSCRIBE Command
2167
2168    Arguments:  mailbox name
2169
2170    Responses:  no specific responses for this command
2171
2172    Result:     OK - unsubscribe completed
2173                NO - unsubscribe failure: can't unsubscribe that name
2174                BAD - command unknown or arguments invalid
2175
2176       The UNSUBSCRIBE command removes the specified mailbox name from
2177       the server's set of "active" or "subscribed" mailboxes as returned
2178       by the LSUB command.  This command returns a tagged OK response
2179       only if the unsubscription is successful.
2180
2181    Example:    C: A002 UNSUBSCRIBE #news.comp.mail.mime
2182                S: A002 OK UNSUBSCRIBE completed
2183
2184
2185
2186 Crispin                     Standards Track                    [Page 39]
2187 \f
2188 RFC 3501                         IMAPv4                       March 2003
2189
2190
2191 6.3.8.  LIST Command
2192
2193    Arguments:  reference name
2194                mailbox name with possible wildcards
2195
2196    Responses:  untagged responses: LIST
2197
2198    Result:     OK - list completed
2199                NO - list failure: can't list that reference or name
2200                BAD - command unknown or arguments invalid
2201
2202       The LIST command returns a subset of names from the complete set
2203       of all names available to the client.  Zero or more untagged LIST
2204       replies are returned, containing the name attributes, hierarchy
2205       delimiter, and name; see the description of the LIST reply for
2206       more detail.
2207
2208       The LIST command SHOULD return its data quickly, without undue
2209       delay.  For example, it SHOULD NOT go to excess trouble to
2210       calculate the \Marked or \Unmarked status or perform other
2211       processing; if each name requires 1 second of processing, then a
2212       list of 1200 names would take 20 minutes!
2213
2214       An empty ("" string) reference name argument indicates that the
2215       mailbox name is interpreted as by SELECT.  The returned mailbox
2216       names MUST match the supplied mailbox name pattern.  A non-empty
2217       reference name argument is the name of a mailbox or a level of
2218       mailbox hierarchy, and indicates the context in which the mailbox
2219       name is interpreted.
2220
2221       An empty ("" string) mailbox name argument is a special request to
2222       return the hierarchy delimiter and the root name of the name given
2223       in the reference.  The value returned as the root MAY be the empty
2224       string if the reference is non-rooted or is an empty string.  In
2225       all cases, a hierarchy delimiter (or NIL if there is no hierarchy)
2226       is returned.  This permits a client to get the hierarchy delimiter
2227       (or find out that the mailbox names are flat) even when no
2228       mailboxes by that name currently exist.
2229
2230       The reference and mailbox name arguments are interpreted into a
2231       canonical form that represents an unambiguous left-to-right
2232       hierarchy.  The returned mailbox names will be in the interpreted
2233       form.
2234
2235
2236
2237
2238
2239
2240
2241
2242 Crispin                     Standards Track                    [Page 40]
2243 \f
2244 RFC 3501                         IMAPv4                       March 2003
2245
2246
2247            Note: The interpretation of the reference argument is
2248            implementation-defined.  It depends upon whether the
2249            server implementation has a concept of the "current
2250            working directory" and leading "break out characters",
2251            which override the current working directory.
2252
2253            For example, on a server which exports a UNIX or NT
2254            filesystem, the reference argument contains the current
2255            working directory, and the mailbox name argument would
2256            contain the name as interpreted in the current working
2257            directory.
2258
2259            If a server implementation has no concept of break out
2260            characters, the canonical form is normally the reference
2261            name appended with the mailbox name.  Note that if the
2262            server implements the namespace convention (section
2263            5.1.2), "#" is a break out character and must be treated
2264            as such.
2265
2266            If the reference argument is not a level of mailbox
2267            hierarchy (that is, it is a \NoInferiors name), and/or
2268            the reference argument does not end with the hierarchy
2269            delimiter, it is implementation-dependent how this is
2270            interpreted.  For example, a reference of "foo/bar" and
2271            mailbox name of "rag/baz" could be interpreted as
2272            "foo/bar/rag/baz", "foo/barrag/baz", or "foo/rag/baz".
2273            A client SHOULD NOT use such a reference argument except
2274            at the explicit request of the user.  A hierarchical
2275            browser MUST NOT make any assumptions about server
2276            interpretation of the reference unless the reference is
2277            a level of mailbox hierarchy AND ends with the hierarchy
2278            delimiter.
2279
2280       Any part of the reference argument that is included in the
2281       interpreted form SHOULD prefix the interpreted form.  It SHOULD
2282       also be in the same form as the reference name argument.  This
2283       rule permits the client to determine if the returned mailbox name
2284       is in the context of the reference argument, or if something about
2285       the mailbox argument overrode the reference argument.  Without
2286       this rule, the client would have to have knowledge of the server's
2287       naming semantics including what characters are "breakouts" that
2288       override a naming context.
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298 Crispin                     Standards Track                    [Page 41]
2299 \f
2300 RFC 3501                         IMAPv4                       March 2003
2301
2302
2303            For example, here are some examples of how references
2304            and mailbox names might be interpreted on a UNIX-based
2305            server:
2306
2307                Reference     Mailbox Name  Interpretation
2308                ------------  ------------  --------------
2309                ~smith/Mail/  foo.*         ~smith/Mail/foo.*
2310                archive/      %             archive/%
2311                #news.        comp.mail.*   #news.comp.mail.*
2312                ~smith/Mail/  /usr/doc/foo  /usr/doc/foo
2313                archive/      ~fred/Mail/*  ~fred/Mail/*
2314
2315            The first three examples demonstrate interpretations in
2316            the context of the reference argument.  Note that
2317            "~smith/Mail" SHOULD NOT be transformed into something
2318            like "/u2/users/smith/Mail", or it would be impossible
2319            for the client to determine that the interpretation was
2320            in the context of the reference.
2321
2322       The character "*" is a wildcard, and matches zero or more
2323       characters at this position.  The character "%" is similar to "*",
2324       but it does not match a hierarchy delimiter.  If the "%" wildcard
2325       is the last character of a mailbox name argument, matching levels
2326       of hierarchy are also returned.  If these levels of hierarchy are
2327       not also selectable mailboxes, they are returned with the
2328       \Noselect mailbox name attribute (see the description of the LIST
2329       response for more details).
2330
2331       Server implementations are permitted to "hide" otherwise
2332       accessible mailboxes from the wildcard characters, by preventing
2333       certain characters or names from matching a wildcard in certain
2334       situations.  For example, a UNIX-based server might restrict the
2335       interpretation of "*" so that an initial "/" character does not
2336       match.
2337
2338       The special name INBOX is included in the output from LIST, if
2339       INBOX is supported by this server for this user and if the
2340       uppercase string "INBOX" matches the interpreted reference and
2341       mailbox name arguments with wildcards as described above.  The
2342       criteria for omitting INBOX is whether SELECT INBOX will return
2343       failure; it is not relevant whether the user's real INBOX resides
2344       on this or some other server.
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354 Crispin                     Standards Track                    [Page 42]
2355 \f
2356 RFC 3501                         IMAPv4                       March 2003
2357
2358
2359    Example:    C: A101 LIST "" ""
2360                S: * LIST (\Noselect) "/" ""
2361                S: A101 OK LIST Completed
2362                C: A102 LIST #news.comp.mail.misc ""
2363                S: * LIST (\Noselect) "." #news.
2364                S: A102 OK LIST Completed
2365                C: A103 LIST /usr/staff/jones ""
2366                S: * LIST (\Noselect) "/" /
2367                S: A103 OK LIST Completed
2368                C: A202 LIST ~/Mail/ %
2369                S: * LIST (\Noselect) "/" ~/Mail/foo
2370                S: * LIST () "/" ~/Mail/meetings
2371                S: A202 OK LIST completed
2372
2373
2374 6.3.9.  LSUB Command
2375
2376    Arguments:  reference name
2377                mailbox name with possible wildcards
2378
2379    Responses:  untagged responses: LSUB
2380
2381    Result:     OK - lsub completed
2382                NO - lsub failure: can't list that reference or name
2383                BAD - command unknown or arguments invalid
2384
2385       The LSUB command returns a subset of names from the set of names
2386       that the user has declared as being "active" or "subscribed".
2387       Zero or more untagged LSUB replies are returned.  The arguments to
2388       LSUB are in the same form as those for LIST.
2389
2390       The returned untagged LSUB response MAY contain different mailbox
2391       flags from a LIST untagged response.  If this should happen, the
2392       flags in the untagged LIST are considered more authoritative.
2393
2394       A special situation occurs when using LSUB with the % wildcard.
2395       Consider what happens if "foo/bar" (with a hierarchy delimiter of
2396       "/") is subscribed but "foo" is not.  A "%" wildcard to LSUB must
2397       return foo, not foo/bar, in the LSUB response, and it MUST be
2398       flagged with the \Noselect attribute.
2399
2400       The server MUST NOT unilaterally remove an existing mailbox name
2401       from the subscription list even if a mailbox by that name no
2402       longer exists.
2403
2404
2405
2406
2407
2408
2409
2410 Crispin                     Standards Track                    [Page 43]
2411 \f
2412 RFC 3501                         IMAPv4                       March 2003
2413
2414
2415    Example:    C: A002 LSUB "#news." "comp.mail.*"
2416                S: * LSUB () "." #news.comp.mail.mime
2417                S: * LSUB () "." #news.comp.mail.misc
2418                S: A002 OK LSUB completed
2419                C: A003 LSUB "#news." "comp.%"
2420                S: * LSUB (\NoSelect) "." #news.comp.mail
2421                S: A003 OK LSUB completed
2422
2423
2424 6.3.10. STATUS Command
2425
2426    Arguments:  mailbox name
2427                status data item names
2428
2429    Responses:  untagged responses: STATUS
2430
2431    Result:     OK - status completed
2432                NO - status failure: no status for that name
2433                BAD - command unknown or arguments invalid
2434
2435       The STATUS command requests the status of the indicated mailbox.
2436       It does not change the currently selected mailbox, nor does it
2437       affect the state of any messages in the queried mailbox (in
2438       particular, STATUS MUST NOT cause messages to lose the \Recent
2439       flag).
2440
2441       The STATUS command provides an alternative to opening a second
2442       IMAP4rev1 connection and doing an EXAMINE command on a mailbox to
2443       query that mailbox's status without deselecting the current
2444       mailbox in the first IMAP4rev1 connection.
2445
2446       Unlike the LIST command, the STATUS command is not guaranteed to
2447       be fast in its response.  Under certain circumstances, it can be
2448       quite slow.  In some implementations, the server is obliged to
2449       open the mailbox read-only internally to obtain certain status
2450       information.  Also unlike the LIST command, the STATUS command
2451       does not accept wildcards.
2452
2453            Note: The STATUS command is intended to access the
2454            status of mailboxes other than the currently selected
2455            mailbox.  Because the STATUS command can cause the
2456            mailbox to be opened internally, and because this
2457            information is available by other means on the selected
2458            mailbox, the STATUS command SHOULD NOT be used on the
2459            currently selected mailbox.
2460
2461
2462
2463
2464
2465
2466 Crispin                     Standards Track                    [Page 44]
2467 \f
2468 RFC 3501                         IMAPv4                       March 2003
2469
2470
2471            The STATUS command MUST NOT be used as a "check for new
2472            messages in the selected mailbox" operation (refer to
2473            sections 7, 7.3.1, and 7.3.2 for more information about
2474            the proper method for new message checking).
2475
2476            Because the STATUS command is not guaranteed to be fast
2477            in its results, clients SHOULD NOT expect to be able to
2478            issue many consecutive STATUS commands and obtain
2479            reasonable performance.
2480
2481       The currently defined status data items that can be requested are:
2482
2483       MESSAGES
2484          The number of messages in the mailbox.
2485
2486       RECENT
2487          The number of messages with the \Recent flag set.
2488
2489       UIDNEXT
2490          The next unique identifier value of the mailbox.  Refer to
2491          section 2.3.1.1 for more information.
2492
2493       UIDVALIDITY
2494          The unique identifier validity value of the mailbox.  Refer to
2495          section 2.3.1.1 for more information.
2496
2497       UNSEEN
2498          The number of messages which do not have the \Seen flag set.
2499
2500
2501    Example:    C: A042 STATUS blurdybloop (UIDNEXT MESSAGES)
2502                S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
2503                S: A042 OK STATUS completed
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522 Crispin                     Standards Track                    [Page 45]
2523 \f
2524 RFC 3501                         IMAPv4                       March 2003
2525
2526
2527 6.3.11. APPEND Command
2528
2529    Arguments:  mailbox name
2530                OPTIONAL flag parenthesized list
2531                OPTIONAL date/time string
2532                message literal
2533
2534    Responses:  no specific responses for this command
2535
2536    Result:     OK - append completed
2537                NO - append error: can't append to that mailbox, error
2538                     in flags or date/time or message text
2539                BAD - command unknown or arguments invalid
2540
2541       The APPEND command appends the literal argument as a new message
2542       to the end of the specified destination mailbox.  This argument
2543       SHOULD be in the format of an [RFC-2822] message.  8-bit
2544       characters are permitted in the message.  A server implementation
2545       that is unable to preserve 8-bit data properly MUST be able to
2546       reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB]
2547       content transfer encoding.
2548
2549            Note: There MAY be exceptions, e.g., draft messages, in
2550            which required [RFC-2822] header lines are omitted in
2551            the message literal argument to APPEND.  The full
2552            implications of doing so MUST be understood and
2553            carefully weighed.
2554
2555       If a flag parenthesized list is specified, the flags SHOULD be set
2556       in the resulting message; otherwise, the flag list of the
2557       resulting message is set to empty by default.  In either case, the
2558       Recent flag is also set.
2559
2560       If a date-time is specified, the internal date SHOULD be set in
2561       the resulting message; otherwise, the internal date of the
2562       resulting message is set to the current date and time by default.
2563
2564       If the append is unsuccessful for any reason, the mailbox MUST be
2565       restored to its state before the APPEND attempt; no partial
2566       appending is permitted.
2567
2568       If the destination mailbox does not exist, a server MUST return an
2569       error, and MUST NOT automatically create the mailbox.  Unless it
2570       is certain that the destination mailbox can not be created, the
2571       server MUST send the response code "[TRYCREATE]" as the prefix of
2572       the text of the tagged NO response.  This gives a hint to the
2573       client that it can attempt a CREATE command and retry the APPEND
2574       if the CREATE is successful.
2575
2576
2577
2578 Crispin                     Standards Track                    [Page 46]
2579 \f
2580 RFC 3501                         IMAPv4                       March 2003
2581
2582
2583       If the mailbox is currently selected, the normal new message
2584       actions SHOULD occur.  Specifically, the server SHOULD notify the
2585       client immediately via an untagged EXISTS response.  If the server
2586       does not do so, the client MAY issue a NOOP command (or failing
2587       that, a CHECK command) after one or more APPEND commands.
2588
2589    Example:    C: A003 APPEND saved-messages (\Seen) {310}
2590                S: + Ready for literal data
2591                C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
2592                C: From: Fred Foobar <foobar@Blurdybloop.COM>
2593                C: Subject: afternoon meeting
2594                C: To: mooch@owatagu.siam.edu
2595                C: Message-Id: <B27397-0100000@Blurdybloop.COM>
2596                C: MIME-Version: 1.0
2597                C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
2598                C:
2599                C: Hello Joe, do you think we can meet at 3:30 tomorrow?
2600                C:
2601                S: A003 OK APPEND completed
2602
2603         Note: The APPEND command is not used for message delivery,
2604         because it does not provide a mechanism to transfer [SMTP]
2605         envelope information.
2606
2607 6.4.    Client Commands - Selected State
2608
2609    In the selected state, commands that manipulate messages in a mailbox
2610    are permitted.
2611
2612    In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
2613    and the authenticated state commands (SELECT, EXAMINE, CREATE,
2614    DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, and
2615    APPEND), the following commands are valid in the selected state:
2616    CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, STORE, COPY, and UID.
2617
2618 6.4.1.  CHECK Command
2619
2620    Arguments:  none
2621
2622    Responses:  no specific responses for this command
2623
2624    Result:     OK - check completed
2625                BAD - command unknown or arguments invalid
2626
2627       The CHECK command requests a checkpoint of the currently selected
2628       mailbox.  A checkpoint refers to any implementation-dependent
2629       housekeeping associated with the mailbox (e.g., resolving the
2630       server's in-memory state of the mailbox with the state on its
2631
2632
2633
2634 Crispin                     Standards Track                    [Page 47]
2635 \f
2636 RFC 3501                         IMAPv4                       March 2003
2637
2638
2639       disk) that is not normally executed as part of each command.  A
2640       checkpoint MAY take a non-instantaneous amount of real time to
2641       complete.  If a server implementation has no such housekeeping
2642       considerations, CHECK is equivalent to NOOP.
2643
2644       There is no guarantee that an EXISTS untagged response will happen
2645       as a result of CHECK.  NOOP, not CHECK, SHOULD be used for new
2646       message polling.
2647
2648    Example:    C: FXXZ CHECK
2649                S: FXXZ OK CHECK Completed
2650
2651
2652 6.4.2.  CLOSE Command
2653
2654    Arguments:  none
2655
2656    Responses:  no specific responses for this command
2657
2658    Result:     OK - close completed, now in authenticated state
2659                BAD - command unknown or arguments invalid
2660
2661       The CLOSE command permanently removes all messages that have the
2662       \Deleted flag set from the currently selected mailbox, and returns
2663       to the authenticated state from the selected state.  No untagged
2664       EXPUNGE responses are sent.
2665
2666       No messages are removed, and no error is given, if the mailbox is
2667       selected by an EXAMINE command or is otherwise selected read-only.
2668
2669       Even if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT
2670       command MAY be issued without previously issuing a CLOSE command.
2671       The SELECT, EXAMINE, and LOGOUT commands implicitly close the
2672       currently selected mailbox without doing an expunge.  However,
2673       when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT
2674       sequence is considerably faster than an EXPUNGE-LOGOUT or
2675       EXPUNGE-SELECT because no untagged EXPUNGE responses (which the
2676       client would probably ignore) are sent.
2677
2678    Example:    C: A341 CLOSE
2679                S: A341 OK CLOSE completed
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690 Crispin                     Standards Track                    [Page 48]
2691 \f
2692 RFC 3501                         IMAPv4                       March 2003
2693
2694
2695 6.4.3.  EXPUNGE Command
2696
2697    Arguments:  none
2698
2699    Responses:  untagged responses: EXPUNGE
2700
2701    Result:     OK - expunge completed
2702                NO - expunge failure: can't expunge (e.g., permission
2703                     denied)
2704                BAD - command unknown or arguments invalid
2705
2706       The EXPUNGE command permanently removes all messages that have the
2707       \Deleted flag set from the currently selected mailbox.  Before
2708       returning an OK to the client, an untagged EXPUNGE response is
2709       sent for each message that is removed.
2710
2711    Example:    C: A202 EXPUNGE
2712                S: * 3 EXPUNGE
2713                S: * 3 EXPUNGE
2714                S: * 5 EXPUNGE
2715                S: * 8 EXPUNGE
2716                S: A202 OK EXPUNGE completed
2717
2718         Note: In this example, messages 3, 4, 7, and 11 had the
2719         \Deleted flag set.  See the description of the EXPUNGE
2720         response for further explanation.
2721
2722
2723 6.4.4.  SEARCH Command
2724
2725    Arguments:  OPTIONAL [CHARSET] specification
2726                searching criteria (one or more)
2727
2728    Responses:  REQUIRED untagged response: SEARCH
2729
2730    Result:     OK - search completed
2731                NO - search error: can't search that [CHARSET] or
2732                     criteria
2733                BAD - command unknown or arguments invalid
2734
2735       The SEARCH command searches the mailbox for messages that match
2736       the given searching criteria.  Searching criteria consist of one
2737       or more search keys.  The untagged SEARCH response from the server
2738       contains a listing of message sequence numbers corresponding to
2739       those messages that match the searching criteria.
2740
2741
2742
2743
2744
2745
2746 Crispin                     Standards Track                    [Page 49]
2747 \f
2748 RFC 3501                         IMAPv4                       March 2003
2749
2750
2751       When multiple keys are specified, the result is the intersection
2752       (AND function) of all the messages that match those keys.  For
2753       example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers
2754       to all deleted messages from Smith that were placed in the mailbox
2755       since February 1, 1994.  A search key can also be a parenthesized
2756       list of one or more search keys (e.g., for use with the OR and NOT
2757       keys).
2758
2759       Server implementations MAY exclude [MIME-IMB] body parts with
2760       terminal content media types other than TEXT and MESSAGE from
2761       consideration in SEARCH matching.
2762
2763       The OPTIONAL [CHARSET] specification consists of the word
2764       "CHARSET" followed by a registered [CHARSET].  It indicates the
2765       [CHARSET] of the strings that appear in the search criteria.
2766       [MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in
2767       [RFC-2822]/[MIME-IMB] headers, MUST be decoded before comparing
2768       text in a [CHARSET] other than US-ASCII.  US-ASCII MUST be
2769       supported; other [CHARSET]s MAY be supported.
2770
2771       If the server does not support the specified [CHARSET], it MUST
2772       return a tagged NO response (not a BAD).  This response SHOULD
2773       contain the BADCHARSET response code, which MAY list the
2774       [CHARSET]s supported by the server.
2775
2776       In all search keys that use strings, a message matches the key if
2777       the string is a substring of the field.  The matching is
2778       case-insensitive.
2779
2780       The defined search keys are as follows.  Refer to the Formal
2781       Syntax section for the precise syntactic definitions of the
2782       arguments.
2783
2784       <sequence set>
2785          Messages with message sequence numbers corresponding to the
2786          specified message sequence number set.
2787
2788       ALL
2789          All messages in the mailbox; the default initial key for
2790          ANDing.
2791
2792       ANSWERED
2793          Messages with the \Answered flag set.
2794
2795
2796
2797
2798
2799
2800
2801
2802 Crispin                     Standards Track                    [Page 50]
2803 \f
2804 RFC 3501                         IMAPv4                       March 2003
2805
2806
2807       BCC <string>
2808          Messages that contain the specified string in the envelope
2809          structure's BCC field.
2810
2811       BEFORE <date>
2812          Messages whose internal date (disregarding time and timezone)
2813          is earlier than the specified date.
2814
2815       BODY <string>
2816          Messages that contain the specified string in the body of the
2817          message.
2818
2819       CC <string>
2820          Messages that contain the specified string in the envelope
2821          structure's CC field.
2822
2823       DELETED
2824          Messages with the \Deleted flag set.
2825
2826       DRAFT
2827          Messages with the \Draft flag set.
2828
2829       FLAGGED
2830          Messages with the \Flagged flag set.
2831
2832       FROM <string>
2833          Messages that contain the specified string in the envelope
2834          structure's FROM field.
2835
2836       HEADER <field-name> <string>
2837          Messages that have a header with the specified field-name (as
2838          defined in [RFC-2822]) and that contains the specified string
2839          in the text of the header (what comes after the colon).  If the
2840          string to search is zero-length, this matches all messages that
2841          have a header line with the specified field-name regardless of
2842          the contents.
2843
2844       KEYWORD <flag>
2845          Messages with the specified keyword flag set.
2846
2847       LARGER <n>
2848          Messages with an [RFC-2822] size larger than the specified
2849          number of octets.
2850
2851       NEW
2852          Messages that have the \Recent flag set but not the \Seen flag.
2853          This is functionally equivalent to "(RECENT UNSEEN)".
2854
2855
2856
2857
2858 Crispin                     Standards Track                    [Page 51]
2859 \f
2860 RFC 3501                         IMAPv4                       March 2003
2861
2862
2863       NOT <search-key>
2864          Messages that do not match the specified search key.
2865
2866       OLD
2867          Messages that do not have the \Recent flag set.  This is
2868          functionally equivalent to "NOT RECENT" (as opposed to "NOT
2869          NEW").
2870
2871       ON <date>
2872          Messages whose internal date (disregarding time and timezone)
2873          is within the specified date.
2874
2875       OR <search-key1> <search-key2>
2876          Messages that match either search key.
2877
2878       RECENT
2879          Messages that have the \Recent flag set.
2880
2881       SEEN
2882          Messages that have the \Seen flag set.
2883
2884       SENTBEFORE <date>
2885          Messages whose [RFC-2822] Date: header (disregarding time and
2886          timezone) is earlier than the specified date.
2887
2888       SENTON <date>
2889          Messages whose [RFC-2822] Date: header (disregarding time and
2890          timezone) is within the specified date.
2891
2892       SENTSINCE <date>
2893          Messages whose [RFC-2822] Date: header (disregarding time and
2894          timezone) is within or later than the specified date.
2895
2896       SINCE <date>
2897          Messages whose internal date (disregarding time and timezone)
2898          is within or later than the specified date.
2899
2900       SMALLER <n>
2901          Messages with an [RFC-2822] size smaller than the specified
2902          number of octets.
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914 Crispin                     Standards Track                    [Page 52]
2915 \f
2916 RFC 3501                         IMAPv4                       March 2003
2917
2918
2919       SUBJECT <string>
2920          Messages that contain the specified string in the envelope
2921          structure's SUBJECT field.
2922
2923       TEXT <string>
2924          Messages that contain the specified string in the header or
2925          body of the message.
2926
2927       TO <string>
2928          Messages that contain the specified string in the envelope
2929          structure's TO field.
2930
2931       UID <sequence set>
2932          Messages with unique identifiers corresponding to the specified
2933          unique identifier set.  Sequence set ranges are permitted.
2934
2935       UNANSWERED
2936          Messages that do not have the \Answered flag set.
2937
2938       UNDELETED
2939          Messages that do not have the \Deleted flag set.
2940
2941       UNDRAFT
2942          Messages that do not have the \Draft flag set.
2943
2944       UNFLAGGED
2945          Messages that do not have the \Flagged flag set.
2946
2947       UNKEYWORD <flag>
2948          Messages that do not have the specified keyword flag set.
2949
2950       UNSEEN
2951          Messages that do not have the \Seen flag set.
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970 Crispin                     Standards Track                    [Page 53]
2971 \f
2972 RFC 3501                         IMAPv4                       March 2003
2973
2974
2975    Example:    C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"
2976                S: * SEARCH 2 84 882
2977                S: A282 OK SEARCH completed
2978                C: A283 SEARCH TEXT "string not in mailbox"
2979                S: * SEARCH
2980                S: A283 OK SEARCH completed
2981                C: A284 SEARCH CHARSET UTF-8 TEXT {6}
2982                C: XXXXXX
2983                S: * SEARCH 43
2984                S: A284 OK SEARCH completed
2985
2986         Note: Since this document is restricted to 7-bit ASCII
2987         text, it is not possible to show actual UTF-8 data.  The
2988         "XXXXXX" is a placeholder for what would be 6 octets of
2989         8-bit data in an actual transaction.
2990
2991
2992 6.4.5.  FETCH Command
2993
2994    Arguments:  sequence set
2995                message data item names or macro
2996
2997    Responses:  untagged responses: FETCH
2998
2999    Result:     OK - fetch completed
3000                NO - fetch error: can't fetch that data
3001                BAD - command unknown or arguments invalid
3002
3003       The FETCH command retrieves data associated with a message in the
3004       mailbox.  The data items to be fetched can be either a single atom
3005       or a parenthesized list.
3006
3007       Most data items, identified in the formal syntax under the
3008       msg-att-static rule, are static and MUST NOT change for any
3009       particular message.  Other data items, identified in the formal
3010       syntax under the msg-att-dynamic rule, MAY change, either as a
3011       result of a STORE command or due to external events.
3012
3013            For example, if a client receives an ENVELOPE for a
3014            message when it already knows the envelope, it can
3015            safely ignore the newly transmitted envelope.
3016
3017       There are three macros which specify commonly-used sets of data
3018       items, and can be used instead of data items.  A macro must be
3019       used by itself, and not in conjunction with other macros or data
3020       items.
3021
3022
3023
3024
3025
3026 Crispin                     Standards Track                    [Page 54]
3027 \f
3028 RFC 3501                         IMAPv4                       March 2003
3029
3030
3031       ALL
3032          Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)
3033
3034       FAST
3035          Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE)
3036
3037       FULL
3038          Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE
3039          BODY)
3040
3041       The currently defined data items that can be fetched are:
3042
3043       BODY
3044          Non-extensible form of BODYSTRUCTURE.
3045
3046       BODY[<section>]<<partial>>
3047          The text of a particular body section.  The section
3048          specification is a set of zero or more part specifiers
3049          delimited by periods.  A part specifier is either a part number
3050          or one of the following: HEADER, HEADER.FIELDS,
3051          HEADER.FIELDS.NOT, MIME, and TEXT.  An empty section
3052          specification refers to the entire message, including the
3053          header.
3054
3055          Every message has at least one part number.  Non-[MIME-IMB]
3056          messages, and non-multipart [MIME-IMB] messages with no
3057          encapsulated message, only have a part 1.
3058
3059          Multipart messages are assigned consecutive part numbers, as
3060          they occur in the message.  If a particular part is of type
3061          message or multipart, its parts MUST be indicated by a period
3062          followed by the part number within that nested multipart part.
3063
3064          A part of type MESSAGE/RFC822 also has nested part numbers,
3065          referring to parts of the MESSAGE part's body.
3066
3067          The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and TEXT part
3068          specifiers can be the sole part specifier or can be prefixed by
3069          one or more numeric part specifiers, provided that the numeric
3070          part specifier refers to a part of type MESSAGE/RFC822.  The
3071          MIME part specifier MUST be prefixed by one or more numeric
3072          part specifiers.
3073
3074          The HEADER, HEADER.FIELDS, and HEADER.FIELDS.NOT part
3075          specifiers refer to the [RFC-2822] header of the message or of
3076          an encapsulated [MIME-IMT] MESSAGE/RFC822 message.
3077          HEADER.FIELDS and HEADER.FIELDS.NOT are followed by a list of
3078          field-name (as defined in [RFC-2822]) names, and return a
3079
3080
3081
3082 Crispin                     Standards Track                    [Page 55]
3083 \f
3084 RFC 3501                         IMAPv4                       March 2003
3085
3086
3087          subset of the header.  The subset returned by HEADER.FIELDS
3088          contains only those header fields with a field-name that
3089          matches one of the names in the list; similarly, the subset
3090          returned by HEADER.FIELDS.NOT contains only the header fields
3091          with a non-matching field-name.  The field-matching is
3092          case-insensitive but otherwise exact.  Subsetting does not
3093          exclude the [RFC-2822] delimiting blank line between the header
3094          and the body; the blank line is included in all header fetches,
3095          except in the case of a message which has no body and no blank
3096          line.
3097
3098          The MIME part specifier refers to the [MIME-IMB] header for
3099          this part.
3100
3101          The TEXT part specifier refers to the text body of the message,
3102          omitting the [RFC-2822] header.
3103
3104             Here is an example of a complex message with some of its
3105             part specifiers:
3106
3107        HEADER     ([RFC-2822] header of the message)
3108        TEXT       ([RFC-2822] text body of the message) MULTIPART/MIXED
3109        1          TEXT/PLAIN
3110        2          APPLICATION/OCTET-STREAM
3111        3          MESSAGE/RFC822
3112        3.HEADER   ([RFC-2822] header of the message)
3113        3.TEXT     ([RFC-2822] text body of the message) MULTIPART/MIXED
3114        3.1        TEXT/PLAIN
3115        3.2        APPLICATION/OCTET-STREAM
3116        4          MULTIPART/MIXED
3117        4.1        IMAGE/GIF
3118        4.1.MIME   ([MIME-IMB] header for the IMAGE/GIF)
3119        4.2        MESSAGE/RFC822
3120        4.2.HEADER ([RFC-2822] header of the message)
3121        4.2.TEXT   ([RFC-2822] text body of the message) MULTIPART/MIXED
3122        4.2.1      TEXT/PLAIN
3123        4.2.2      MULTIPART/ALTERNATIVE
3124        4.2.2.1    TEXT/PLAIN
3125        4.2.2.2    TEXT/RICHTEXT
3126
3127
3128          It is possible to fetch a substring of the designated text.
3129          This is done by appending an open angle bracket ("<"), the
3130          octet position of the first desired octet, a period, the
3131          maximum number of octets desired, and a close angle bracket
3132          (">") to the part specifier.  If the starting octet is beyond
3133          the end of the text, an empty string is returned.
3134
3135
3136
3137
3138 Crispin                     Standards Track                    [Page 56]
3139 \f
3140 RFC 3501                         IMAPv4                       March 2003
3141
3142
3143          Any partial fetch that attempts to read beyond the end of the
3144          text is truncated as appropriate.  A partial fetch that starts
3145          at octet 0 is returned as a partial fetch, even if this
3146          truncation happened.
3147
3148             Note: This means that BODY[]<0.2048> of a 1500-octet message
3149             will return BODY[]<0> with a literal of size 1500, not
3150             BODY[].
3151
3152             Note: A substring fetch of a HEADER.FIELDS or
3153             HEADER.FIELDS.NOT part specifier is calculated after
3154             subsetting the header.
3155
3156          The \Seen flag is implicitly set; if this causes the flags to
3157          change, they SHOULD be included as part of the FETCH responses.
3158
3159       BODY.PEEK[<section>]<<partial>>
3160          An alternate form of BODY[<section>] that does not implicitly
3161          set the \Seen flag.
3162
3163       BODYSTRUCTURE
3164          The [MIME-IMB] body structure of the message.  This is computed
3165          by the server by parsing the [MIME-IMB] header fields in the
3166          [RFC-2822] header and [MIME-IMB] headers.
3167
3168       ENVELOPE
3169          The envelope structure of the message.  This is computed by the
3170          server by parsing the [RFC-2822] header into the component
3171          parts, defaulting various fields as necessary.
3172
3173       FLAGS
3174          The flags that are set for this message.
3175
3176       INTERNALDATE
3177          The internal date of the message.
3178
3179       RFC822
3180          Functionally equivalent to BODY[], differing in the syntax of
3181          the resulting untagged FETCH data (RFC822 is returned).
3182
3183       RFC822.HEADER
3184          Functionally equivalent to BODY.PEEK[HEADER], differing in the
3185          syntax of the resulting untagged FETCH data (RFC822.HEADER is
3186          returned).
3187
3188       RFC822.SIZE
3189          The [RFC-2822] size of the message.
3190
3191
3192
3193
3194 Crispin                     Standards Track                    [Page 57]
3195 \f
3196 RFC 3501                         IMAPv4                       March 2003
3197
3198
3199       RFC822.TEXT
3200          Functionally equivalent to BODY[TEXT], differing in the syntax
3201          of the resulting untagged FETCH data (RFC822.TEXT is returned).
3202
3203       UID
3204          The unique identifier for the message.
3205
3206
3207    Example:    C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
3208                S: * 2 FETCH ....
3209                S: * 3 FETCH ....
3210                S: * 4 FETCH ....
3211                S: A654 OK FETCH completed
3212
3213
3214 6.4.6.  STORE Command
3215
3216    Arguments:  sequence set
3217                message data item name
3218                value for message data item
3219
3220    Responses:  untagged responses: FETCH
3221
3222    Result:     OK - store completed
3223                NO - store error: can't store that data
3224                BAD - command unknown or arguments invalid
3225
3226       The STORE command alters data associated with a message in the
3227       mailbox.  Normally, STORE will return the updated value of the
3228       data with an untagged FETCH response.  A suffix of ".SILENT" in
3229       the data item name prevents the untagged FETCH, and the server
3230       SHOULD assume that the client has determined the updated value
3231       itself or does not care about the updated value.
3232
3233            Note: Regardless of whether or not the ".SILENT" suffix
3234            was used, the server SHOULD send an untagged FETCH
3235            response if a change to a message's flags from an
3236            external source is observed.  The intent is that the
3237            status of the flags is determinate without a race
3238            condition.
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250 Crispin                     Standards Track                    [Page 58]
3251 \f
3252 RFC 3501                         IMAPv4                       March 2003
3253
3254
3255       The currently defined data items that can be stored are:
3256
3257       FLAGS <flag list>
3258          Replace the flags for the message (other than \Recent) with the
3259          argument.  The new value of the flags is returned as if a FETCH
3260          of those flags was done.
3261
3262       FLAGS.SILENT <flag list>
3263          Equivalent to FLAGS, but without returning a new value.
3264
3265       +FLAGS <flag list>
3266          Add the argument to the flags for the message.  The new value
3267          of the flags is returned as if a FETCH of those flags was done.
3268
3269       +FLAGS.SILENT <flag list>
3270          Equivalent to +FLAGS, but without returning a new value.
3271
3272       -FLAGS <flag list>
3273          Remove the argument from the flags for the message.  The new
3274          value of the flags is returned as if a FETCH of those flags was
3275          done.
3276
3277       -FLAGS.SILENT <flag list>
3278          Equivalent to -FLAGS, but without returning a new value.
3279
3280
3281    Example:    C: A003 STORE 2:4 +FLAGS (\Deleted)
3282                S: * 2 FETCH (FLAGS (\Deleted \Seen))
3283                S: * 3 FETCH (FLAGS (\Deleted))
3284                S: * 4 FETCH (FLAGS (\Deleted \Flagged \Seen))
3285                S: A003 OK STORE completed
3286
3287
3288 6.4.7.  COPY Command
3289
3290    Arguments:  sequence set
3291                mailbox name
3292
3293    Responses:  no specific responses for this command
3294
3295    Result:     OK - copy completed
3296                NO - copy error: can't copy those messages or to that
3297                     name
3298                BAD - command unknown or arguments invalid
3299
3300
3301
3302
3303
3304
3305
3306 Crispin                     Standards Track                    [Page 59]
3307 \f
3308 RFC 3501                         IMAPv4                       March 2003
3309
3310
3311       The COPY command copies the specified message(s) to the end of the
3312       specified destination mailbox.  The flags and internal date of the
3313       message(s) SHOULD be preserved, and the Recent flag SHOULD be set,
3314       in the copy.
3315
3316       If the destination mailbox does not exist, a server SHOULD return
3317       an error.  It SHOULD NOT automatically create the mailbox.  Unless
3318       it is certain that the destination mailbox can not be created, the
3319       server MUST send the response code "[TRYCREATE]" as the prefix of
3320       the text of the tagged NO response.  This gives a hint to the
3321       client that it can attempt a CREATE command and retry the COPY if
3322       the CREATE is successful.
3323
3324       If the COPY command is unsuccessful for any reason, server
3325       implementations MUST restore the destination mailbox to its state
3326       before the COPY attempt.
3327
3328    Example:    C: A003 COPY 2:4 MEETING
3329                S: A003 OK COPY completed
3330
3331
3332 6.4.8.  UID Command
3333
3334    Arguments:  command name
3335                command arguments
3336
3337    Responses:  untagged responses: FETCH, SEARCH
3338
3339    Result:     OK - UID command completed
3340                NO - UID command error
3341                BAD - command unknown or arguments invalid
3342
3343       The UID command has two forms.  In the first form, it takes as its
3344       arguments a COPY, FETCH, or STORE command with arguments
3345       appropriate for the associated command.  However, the numbers in
3346       the sequence set argument are unique identifiers instead of
3347       message sequence numbers.  Sequence set ranges are permitted, but
3348       there is no guarantee that unique identifiers will be contiguous.
3349
3350       A non-existent unique identifier is ignored without any error
3351       message generated.  Thus, it is possible for a UID FETCH command
3352       to return an OK without any data or a UID COPY or UID STORE to
3353       return an OK without performing any operations.
3354
3355       In the second form, the UID command takes a SEARCH command with
3356       SEARCH command arguments.  The interpretation of the arguments is
3357       the same as with SEARCH; however, the numbers returned in a SEARCH
3358       response for a UID SEARCH command are unique identifiers instead
3359
3360
3361
3362 Crispin                     Standards Track                    [Page 60]
3363 \f
3364 RFC 3501                         IMAPv4                       March 2003
3365
3366
3367       of message sequence numbers.  For example, the command UID SEARCH
3368       1:100 UID 443:557 returns the unique identifiers corresponding to
3369       the intersection of two sequence sets, the message sequence number
3370       range 1:100 and the UID range 443:557.
3371
3372            Note: in the above example, the UID range 443:557
3373            appears.  The same comment about a non-existent unique
3374            identifier being ignored without any error message also
3375            applies here.  Hence, even if neither UID 443 or 557
3376            exist, this range is valid and would include an existing
3377            UID 495.
3378
3379            Also note that a UID range of 559:* always includes the
3380            UID of the last message in the mailbox, even if 559 is
3381            higher than any assigned UID value.  This is because the
3382            contents of a range are independent of the order of the
3383            range endpoints.  Thus, any UID range with * as one of
3384            the endpoints indicates at least one message (the
3385            message with the highest numbered UID), unless the
3386            mailbox is empty.
3387
3388       The number after the "*" in an untagged FETCH response is always a
3389       message sequence number, not a unique identifier, even for a UID
3390       command response.  However, server implementations MUST implicitly
3391       include the UID message data item as part of any FETCH response
3392       caused by a UID command, regardless of whether a UID was specified
3393       as a message data item to the FETCH.
3394
3395
3396       Note: The rule about including the UID message data item as part
3397       of a FETCH response primarily applies to the UID FETCH and UID
3398       STORE commands, including a UID FETCH command that does not
3399       include UID as a message data item.  Although it is unlikely that
3400       the other UID commands will cause an untagged FETCH, this rule
3401       applies to these commands as well.
3402
3403    Example:    C: A999 UID FETCH 4827313:4828442 FLAGS
3404                S: * 23 FETCH (FLAGS (\Seen) UID 4827313)
3405                S: * 24 FETCH (FLAGS (\Seen) UID 4827943)
3406                S: * 25 FETCH (FLAGS (\Seen) UID 4828442)
3407                S: A999 OK UID FETCH completed
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418 Crispin                     Standards Track                    [Page 61]
3419 \f
3420 RFC 3501                         IMAPv4                       March 2003
3421
3422
3423 6.5.    Client Commands - Experimental/Expansion
3424
3425
3426 6.5.1.  X<atom> Command
3427
3428    Arguments:  implementation defined
3429
3430    Responses:  implementation defined
3431
3432    Result:     OK - command completed
3433                NO - failure
3434                BAD - command unknown or arguments invalid
3435
3436       Any command prefixed with an X is an experimental command.
3437       Commands which are not part of this specification, a standard or
3438       standards-track revision of this specification, or an
3439       IESG-approved experimental protocol, MUST use the X prefix.
3440
3441       Any added untagged responses issued by an experimental command
3442       MUST also be prefixed with an X.  Server implementations MUST NOT
3443       send any such untagged responses, unless the client requested it
3444       by issuing the associated experimental command.
3445
3446    Example:    C: a441 CAPABILITY
3447                S: * CAPABILITY IMAP4rev1 XPIG-LATIN
3448                S: a441 OK CAPABILITY completed
3449                C: A442 XPIG-LATIN
3450                S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay
3451                S: A442 OK XPIG-LATIN ompleted-cay
3452
3453 7.      Server Responses
3454
3455    Server responses are in three forms: status responses, server data,
3456    and command continuation request.  The information contained in a
3457    server response, identified by "Contents:" in the response
3458    descriptions below, is described by function, not by syntax.  The
3459    precise syntax of server responses is described in the Formal Syntax
3460    section.
3461
3462    The client MUST be prepared to accept any response at all times.
3463
3464    Status responses can be tagged or untagged.  Tagged status responses
3465    indicate the completion result (OK, NO, or BAD status) of a client
3466    command, and have a tag matching the command.
3467
3468    Some status responses, and all server data, are untagged.  An
3469    untagged response is indicated by the token "*" instead of a tag.
3470    Untagged status responses indicate server greeting, or server status
3471
3472
3473
3474 Crispin                     Standards Track                    [Page 62]
3475 \f
3476 RFC 3501                         IMAPv4                       March 2003
3477
3478
3479    that does not indicate the completion of a command (for example, an
3480    impending system shutdown alert).  For historical reasons, untagged
3481    server data responses are also called "unsolicited data", although
3482    strictly speaking, only unilateral server data is truly
3483    "unsolicited".
3484
3485    Certain server data MUST be recorded by the client when it is
3486    received; this is noted in the description of that data.  Such data
3487    conveys critical information which affects the interpretation of all
3488    subsequent commands and responses (e.g., updates reflecting the
3489    creation or destruction of messages).
3490
3491    Other server data SHOULD be recorded for later reference; if the
3492    client does not need to record the data, or if recording the data has
3493    no obvious purpose (e.g., a SEARCH response when no SEARCH command is
3494    in progress), the data SHOULD be ignored.
3495
3496    An example of unilateral untagged server data occurs when the IMAP
3497    connection is in the selected state.  In the selected state, the
3498    server checks the mailbox for new messages as part of command
3499    execution.  Normally, this is part of the execution of every command;
3500    hence, a NOOP command suffices to check for new messages.  If new
3501    messages are found, the server sends untagged EXISTS and RECENT
3502    responses reflecting the new size of the mailbox.  Server
3503    implementations that offer multiple simultaneous access to the same
3504    mailbox SHOULD also send appropriate unilateral untagged FETCH and
3505    EXPUNGE responses if another agent changes the state of any message
3506    flags or expunges any messages.
3507
3508    Command continuation request responses use the token "+" instead of a
3509    tag.  These responses are sent by the server to indicate acceptance
3510    of an incomplete client command and readiness for the remainder of
3511    the command.
3512
3513 7.1.    Server Responses - Status Responses
3514
3515    Status responses are OK, NO, BAD, PREAUTH and BYE.  OK, NO, and BAD
3516    can be tagged or untagged.  PREAUTH and BYE are always untagged.
3517
3518    Status responses MAY include an OPTIONAL "response code".  A response
3519    code consists of data inside square brackets in the form of an atom,
3520    possibly followed by a space and arguments.  The response code
3521    contains additional information or status codes for client software
3522    beyond the OK/NO/BAD condition, and are defined when there is a
3523    specific