rfc3501.txt - rohrpost - A commandline mail client to change the world as we see it.
(HTM) git clone git://r-36.net/rohrpost
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
rfc3501.txt (227639B)
---
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 action that a client can take based upon the additional
3524 information.
3525
3526
3527
3528
3529
3530 Crispin Standards Track [Page 63]
3531
3532 RFC 3501 IMAPv4 March 2003
3533
3534
3535 The currently defined response codes are:
3536
3537 ALERT
3538
3539 The human-readable text contains a special alert that MUST be
3540 presented to the user in a fashion that calls the user's
3541 attention to the message.
3542
3543 BADCHARSET
3544
3545 Optionally followed by a parenthesized list of charsets. A
3546 SEARCH failed because the given charset is not supported by
3547 this implementation. If the optional list of charsets is
3548 given, this lists the charsets that are supported by this
3549 implementation.
3550
3551 CAPABILITY
3552
3553 Followed by a list of capabilities. This can appear in the
3554 initial OK or PREAUTH response to transmit an initial
3555 capabilities list. This makes it unnecessary for a client to
3556 send a separate CAPABILITY command if it recognizes this
3557 response.
3558
3559 PARSE
3560
3561 The human-readable text represents an error in parsing the
3562 [RFC-2822] header or [MIME-IMB] headers of a message in the
3563 mailbox.
3564
3565 PERMANENTFLAGS
3566
3567 Followed by a parenthesized list of flags, indicates which of
3568 the known flags the client can change permanently. Any flags
3569 that are in the FLAGS untagged response, but not the
3570 PERMANENTFLAGS list, can not be set permanently. If the client
3571 attempts to STORE a flag that is not in the PERMANENTFLAGS
3572 list, the server will either ignore the change or store the
3573 state change for the remainder of the current session only.
3574 The PERMANENTFLAGS list can also include the special flag \*,
3575 which indicates that it is possible to create new keywords by
3576 attempting to store those flags in the mailbox.
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586 Crispin Standards Track [Page 64]
3587
3588 RFC 3501 IMAPv4 March 2003
3589
3590
3591 READ-ONLY
3592
3593 The mailbox is selected read-only, or its access while selected
3594 has changed from read-write to read-only.
3595
3596 READ-WRITE
3597
3598 The mailbox is selected read-write, or its access while
3599 selected has changed from read-only to read-write.
3600
3601 TRYCREATE
3602
3603 An APPEND or COPY attempt is failing because the target mailbox
3604 does not exist (as opposed to some other reason). This is a
3605 hint to the client that the operation can succeed if the
3606 mailbox is first created by the CREATE command.
3607
3608 UIDNEXT
3609
3610 Followed by a decimal number, indicates the next unique
3611 identifier value. Refer to section 2.3.1.1 for more
3612 information.
3613
3614 UIDVALIDITY
3615
3616 Followed by a decimal number, indicates the unique identifier
3617 validity value. Refer to section 2.3.1.1 for more information.
3618
3619 UNSEEN
3620
3621 Followed by a decimal number, indicates the number of the first
3622 message without the \Seen flag set.
3623
3624 Additional response codes defined by particular client or server
3625 implementations SHOULD be prefixed with an "X" until they are
3626 added to a revision of this protocol. Client implementations
3627 SHOULD ignore response codes that they do not recognize.
3628
3629 7.1.1. OK Response
3630
3631 Contents: OPTIONAL response code
3632 human-readable text
3633
3634 The OK response indicates an information message from the server.
3635 When tagged, it indicates successful completion of the associated
3636 command. The human-readable text MAY be presented to the user as
3637 an information message. The untagged form indicates an
3638
3639
3640
3641
3642 Crispin Standards Track [Page 65]
3643
3644 RFC 3501 IMAPv4 March 2003
3645
3646
3647 information-only message; the nature of the information MAY be
3648 indicated by a response code.
3649
3650 The untagged form is also used as one of three possible greetings
3651 at connection startup. It indicates that the connection is not
3652 yet authenticated and that a LOGIN command is needed.
3653
3654 Example: S: * OK IMAP4rev1 server ready
3655 C: A001 LOGIN fred blurdybloop
3656 S: * OK [ALERT] System shutdown in 10 minutes
3657 S: A001 OK LOGIN Completed
3658
3659
3660 7.1.2. NO Response
3661
3662 Contents: OPTIONAL response code
3663 human-readable text
3664
3665 The NO response indicates an operational error message from the
3666 server. When tagged, it indicates unsuccessful completion of the
3667 associated command. The untagged form indicates a warning; the
3668 command can still complete successfully. The human-readable text
3669 describes the condition.
3670
3671 Example: C: A222 COPY 1:2 owatagusiam
3672 S: * NO Disk is 98% full, please delete unnecessary data
3673 S: A222 OK COPY completed
3674 C: A223 COPY 3:200 blurdybloop
3675 S: * NO Disk is 98% full, please delete unnecessary data
3676 S: * NO Disk is 99% full, please delete unnecessary data
3677 S: A223 NO COPY failed: disk is full
3678
3679
3680 7.1.3. BAD Response
3681
3682 Contents: OPTIONAL response code
3683 human-readable text
3684
3685 The BAD response indicates an error message from the server. When
3686 tagged, it reports a protocol-level error in the client's command;
3687 the tag indicates the command that caused the error. The untagged
3688 form indicates a protocol-level error for which the associated
3689 command can not be determined; it can also indicate an internal
3690 server failure. The human-readable text describes the condition.
3691
3692
3693
3694
3695
3696
3697
3698 Crispin Standards Track [Page 66]
3699
3700 RFC 3501 IMAPv4 March 2003
3701
3702
3703 Example: C: ...very long command line...
3704 S: * BAD Command line too long
3705 C: ...empty line...
3706 S: * BAD Empty command line
3707 C: A443 EXPUNGE
3708 S: * BAD Disk crash, attempting salvage to a new disk!
3709 S: * OK Salvage successful, no data lost
3710 S: A443 OK Expunge completed
3711
3712
3713 7.1.4. PREAUTH Response
3714
3715 Contents: OPTIONAL response code
3716 human-readable text
3717
3718 The PREAUTH response is always untagged, and is one of three
3719 possible greetings at connection startup. It indicates that the
3720 connection has already been authenticated by external means; thus
3721 no LOGIN command is needed.
3722
3723 Example: S: * PREAUTH IMAP4rev1 server logged in as Smith
3724
3725
3726 7.1.5. BYE Response
3727
3728 Contents: OPTIONAL response code
3729 human-readable text
3730
3731 The BYE response is always untagged, and indicates that the server
3732 is about to close the connection. The human-readable text MAY be
3733 displayed to the user in a status report by the client. The BYE
3734 response is sent under one of four conditions:
3735
3736 1) as part of a normal logout sequence. The server will close
3737 the connection after sending the tagged OK response to the
3738 LOGOUT command.
3739
3740 2) as a panic shutdown announcement. The server closes the
3741 connection immediately.
3742
3743 3) as an announcement of an inactivity autologout. The server
3744 closes the connection immediately.
3745
3746 4) as one of three possible greetings at connection startup,
3747 indicating that the server is not willing to accept a
3748 connection from this client. The server closes the
3749 connection immediately.
3750
3751
3752
3753
3754 Crispin Standards Track [Page 67]
3755
3756 RFC 3501 IMAPv4 March 2003
3757
3758
3759 The difference between a BYE that occurs as part of a normal
3760 LOGOUT sequence (the first case) and a BYE that occurs because of
3761 a failure (the other three cases) is that the connection closes
3762 immediately in the failure case. In all cases the client SHOULD
3763 continue to read response data from the server until the
3764 connection is closed; this will ensure that any pending untagged
3765 or completion responses are read and processed.
3766
3767 Example: S: * BYE Autologout; idle for too long
3768
3769 7.2. Server Responses - Server and Mailbox Status
3770
3771 These responses are always untagged. This is how server and mailbox
3772 status data are transmitted from the server to the client. Many of
3773 these responses typically result from a command with the same name.
3774
3775 7.2.1. CAPABILITY Response
3776
3777 Contents: capability listing
3778
3779 The CAPABILITY response occurs as a result of a CAPABILITY
3780 command. The capability listing contains a space-separated
3781 listing of capability names that the server supports. The
3782 capability listing MUST include the atom "IMAP4rev1".
3783
3784 In addition, client and server implementations MUST implement the
3785 STARTTLS, LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS])
3786 capabilities. See the Security Considerations section for
3787 important information.
3788
3789 A capability name which begins with "AUTH=" indicates that the
3790 server supports that particular authentication mechanism.
3791
3792 The LOGINDISABLED capability indicates that the LOGIN command is
3793 disabled, and that the server will respond with a tagged NO
3794 response to any attempt to use the LOGIN command even if the user
3795 name and password are valid. An IMAP client MUST NOT issue the
3796 LOGIN command if the server advertises the LOGINDISABLED
3797 capability.
3798
3799 Other capability names indicate that the server supports an
3800 extension, revision, or amendment to the IMAP4rev1 protocol.
3801 Server responses MUST conform to this document until the client
3802 issues a command that uses the associated capability.
3803
3804 Capability names MUST either begin with "X" or be standard or
3805 standards-track IMAP4rev1 extensions, revisions, or amendments
3806 registered with IANA. A server MUST NOT offer unregistered or
3807
3808
3809
3810 Crispin Standards Track [Page 68]
3811
3812 RFC 3501 IMAPv4 March 2003
3813
3814
3815 non-standard capability names, unless such names are prefixed with
3816 an "X".
3817
3818 Client implementations SHOULD NOT require any capability name
3819 other than "IMAP4rev1", and MUST ignore any unknown capability
3820 names.
3821
3822 A server MAY send capabilities automatically, by using the
3823 CAPABILITY response code in the initial PREAUTH or OK responses,
3824 and by sending an updated CAPABILITY response code in the tagged
3825 OK response as part of a successful authentication. It is
3826 unnecessary for a client to send a separate CAPABILITY command if
3827 it recognizes these automatic capabilities.
3828
3829 Example: S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI XPIG-LATIN
3830
3831
3832 7.2.2. LIST Response
3833
3834 Contents: name attributes
3835 hierarchy delimiter
3836 name
3837
3838 The LIST response occurs as a result of a LIST command. It
3839 returns a single name that matches the LIST specification. There
3840 can be multiple LIST responses for a single LIST command.
3841
3842 Four name attributes are defined:
3843
3844 \Noinferiors
3845 It is not possible for any child levels of hierarchy to exist
3846 under this name; no child levels exist now and none can be
3847 created in the future.
3848
3849 \Noselect
3850 It is not possible to use this name as a selectable mailbox.
3851
3852 \Marked
3853 The mailbox has been marked "interesting" by the server; the
3854 mailbox probably contains messages that have been added since
3855 the last time the mailbox was selected.
3856
3857 \Unmarked
3858 The mailbox does not contain any additional messages since the
3859 last time the mailbox was selected.
3860
3861
3862
3863
3864
3865
3866 Crispin Standards Track [Page 69]
3867
3868 RFC 3501 IMAPv4 March 2003
3869
3870
3871 If it is not feasible for the server to determine whether or not
3872 the mailbox is "interesting", or if the name is a \Noselect name,
3873 the server SHOULD NOT send either \Marked or \Unmarked.
3874
3875 The hierarchy delimiter is a character used to delimit levels of
3876 hierarchy in a mailbox name. A client can use it to create child
3877 mailboxes, and to search higher or lower levels of naming
3878 hierarchy. All children of a top-level hierarchy node MUST use
3879 the same separator character. A NIL hierarchy delimiter means
3880 that no hierarchy exists; the name is a "flat" name.
3881
3882 The name represents an unambiguous left-to-right hierarchy, and
3883 MUST be valid for use as a reference in LIST and LSUB commands.
3884 Unless \Noselect is indicated, the name MUST also be valid as an
3885 argument for commands, such as SELECT, that accept mailbox names.
3886
3887 Example: S: * LIST (\Noselect) "/" ~/Mail/foo
3888
3889
3890 7.2.3. LSUB Response
3891
3892 Contents: name attributes
3893 hierarchy delimiter
3894 name
3895
3896 The LSUB response occurs as a result of an LSUB command. It
3897 returns a single name that matches the LSUB specification. There
3898 can be multiple LSUB responses for a single LSUB command. The
3899 data is identical in format to the LIST response.
3900
3901 Example: S: * LSUB () "." #news.comp.mail.misc
3902
3903
3904 7.2.4 STATUS Response
3905
3906 Contents: name
3907 status parenthesized list
3908
3909 The STATUS response occurs as a result of an STATUS command. It
3910 returns the mailbox name that matches the STATUS specification and
3911 the requested mailbox status information.
3912
3913 Example: S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
3914
3915
3916
3917
3918
3919
3920
3921
3922 Crispin Standards Track [Page 70]
3923
3924 RFC 3501 IMAPv4 March 2003
3925
3926
3927 7.2.5. SEARCH Response
3928
3929 Contents: zero or more numbers
3930
3931 The SEARCH response occurs as a result of a SEARCH or UID SEARCH
3932 command. The number(s) refer to those messages that match the
3933 search criteria. For SEARCH, these are message sequence numbers;
3934 for UID SEARCH, these are unique identifiers. Each number is
3935 delimited by a space.
3936
3937 Example: S: * SEARCH 2 3 6
3938
3939
3940 7.2.6. FLAGS Response
3941
3942 Contents: flag parenthesized list
3943
3944 The FLAGS response occurs as a result of a SELECT or EXAMINE
3945 command. The flag parenthesized list identifies the flags (at a
3946 minimum, the system-defined flags) that are applicable for this
3947 mailbox. Flags other than the system flags can also exist,
3948 depending on server implementation.
3949
3950 The update from the FLAGS response MUST be recorded by the client.
3951
3952 Example: S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
3953
3954
3955 7.3. Server Responses - Mailbox Size
3956
3957 These responses are always untagged. This is how changes in the size
3958 of the mailbox are transmitted from the server to the client.
3959 Immediately following the "*" token is a number that represents a
3960 message count.
3961
3962 7.3.1. EXISTS Response
3963
3964 Contents: none
3965
3966 The EXISTS response reports the number of messages in the mailbox.
3967 This response occurs as a result of a SELECT or EXAMINE command,
3968 and if the size of the mailbox changes (e.g., new messages).
3969
3970 The update from the EXISTS response MUST be recorded by the
3971 client.
3972
3973 Example: S: * 23 EXISTS
3974
3975
3976
3977
3978 Crispin Standards Track [Page 71]
3979
3980 RFC 3501 IMAPv4 March 2003
3981
3982
3983 7.3.2. RECENT Response
3984
3985 Contents: none
3986
3987 The RECENT response reports the number of messages with the
3988 \Recent flag set. This response occurs as a result of a SELECT or
3989 EXAMINE command, and if the size of the mailbox changes (e.g., new
3990 messages).
3991
3992 Note: It is not guaranteed that the message sequence
3993 numbers of recent messages will be a contiguous range of
3994 the highest n messages in the mailbox (where n is the
3995 value reported by the RECENT response). Examples of
3996 situations in which this is not the case are: multiple
3997 clients having the same mailbox open (the first session
3998 to be notified will see it as recent, others will
3999 probably see it as non-recent), and when the mailbox is
4000 re-ordered by a non-IMAP agent.
4001
4002 The only reliable way to identify recent messages is to
4003 look at message flags to see which have the \Recent flag
4004 set, or to do a SEARCH RECENT.
4005
4006 The update from the RECENT response MUST be recorded by the
4007 client.
4008
4009 Example: S: * 5 RECENT
4010
4011
4012 7.4. Server Responses - Message Status
4013
4014 These responses are always untagged. This is how message data are
4015 transmitted from the server to the client, often as a result of a
4016 command with the same name. Immediately following the "*" token is a
4017 number that represents a message sequence number.
4018
4019 7.4.1. EXPUNGE Response
4020
4021 Contents: none
4022
4023 The EXPUNGE response reports that the specified message sequence
4024 number has been permanently removed from the mailbox. The message
4025 sequence number for each successive message in the mailbox is
4026 immediately decremented by 1, and this decrement is reflected in
4027 message sequence numbers in subsequent responses (including other
4028 untagged EXPUNGE responses).
4029
4030
4031
4032
4033
4034 Crispin Standards Track [Page 72]
4035
4036 RFC 3501 IMAPv4 March 2003
4037
4038
4039 The EXPUNGE response also decrements the number of messages in the
4040 mailbox; it is not necessary to send an EXISTS response with the
4041 new value.
4042
4043 As a result of the immediate decrement rule, message sequence
4044 numbers that appear in a set of successive EXPUNGE responses
4045 depend upon whether the messages are removed starting from lower
4046 numbers to higher numbers, or from higher numbers to lower
4047 numbers. For example, if the last 5 messages in a 9-message
4048 mailbox are expunged, a "lower to higher" server will send five
4049 untagged EXPUNGE responses for message sequence number 5, whereas
4050 a "higher to lower server" will send successive untagged EXPUNGE
4051 responses for message sequence numbers 9, 8, 7, 6, and 5.
4052
4053 An EXPUNGE response MUST NOT be sent when no command is in
4054 progress, nor while responding to a FETCH, STORE, or SEARCH
4055 command. This rule is necessary to prevent a loss of
4056 synchronization of message sequence numbers between client and
4057 server. A command is not "in progress" until the complete command
4058 has been received; in particular, a command is not "in progress"
4059 during the negotiation of command continuation.
4060
4061 Note: UID FETCH, UID STORE, and UID SEARCH are different
4062 commands from FETCH, STORE, and SEARCH. An EXPUNGE
4063 response MAY be sent during a UID command.
4064
4065 The update from the EXPUNGE response MUST be recorded by the
4066 client.
4067
4068 Example: S: * 44 EXPUNGE
4069
4070
4071 7.4.2. FETCH Response
4072
4073 Contents: message data
4074
4075 The FETCH response returns data about a message to the client.
4076 The data are pairs of data item names and their values in
4077 parentheses. This response occurs as the result of a FETCH or
4078 STORE command, as well as by unilateral server decision (e.g.,
4079 flag updates).
4080
4081 The current data items are:
4082
4083 BODY
4084 A form of BODYSTRUCTURE without extension data.
4085
4086
4087
4088
4089
4090 Crispin Standards Track [Page 73]
4091
4092 RFC 3501 IMAPv4 March 2003
4093
4094
4095 BODY[<section>]<<origin octet>>
4096 A string expressing the body contents of the specified section.
4097 The string SHOULD be interpreted by the client according to the
4098 content transfer encoding, body type, and subtype.
4099
4100 If the origin octet is specified, this string is a substring of
4101 the entire body contents, starting at that origin octet. This
4102 means that BODY[]<0> MAY be truncated, but BODY[] is NEVER
4103 truncated.
4104
4105 Note: The origin octet facility MUST NOT be used by a server
4106 in a FETCH response unless the client specifically requested
4107 it by means of a FETCH of a BODY[<section>]<<partial>> data
4108 item.
4109
4110 8-bit textual data is permitted if a [CHARSET] identifier is
4111 part of the body parameter parenthesized list for this section.
4112 Note that headers (part specifiers HEADER or MIME, or the
4113 header portion of a MESSAGE/RFC822 part), MUST be 7-bit; 8-bit
4114 characters are not permitted in headers. Note also that the
4115 [RFC-2822] delimiting blank line between the header and the
4116 body is not affected by header line subsetting; the blank line
4117 is always included as part of header data, except in the case
4118 of a message which has no body and no blank line.
4119
4120 Non-textual data such as binary data MUST be transfer encoded
4121 into a textual form, such as BASE64, prior to being sent to the
4122 client. To derive the original binary data, the client MUST
4123 decode the transfer encoded string.
4124
4125 BODYSTRUCTURE
4126 A parenthesized list that describes the [MIME-IMB] body
4127 structure of a message. This is computed by the server by
4128 parsing the [MIME-IMB] header fields, defaulting various fields
4129 as necessary.
4130
4131 For example, a simple text message of 48 lines and 2279 octets
4132 can have a body structure of: ("TEXT" "PLAIN" ("CHARSET"
4133 "US-ASCII") NIL NIL "7BIT" 2279 48)
4134
4135 Multiple parts are indicated by parenthesis nesting. Instead
4136 of a body type as the first element of the parenthesized list,
4137 there is a sequence of one or more nested body structures. The
4138 second element of the parenthesized list is the multipart
4139 subtype (mixed, digest, parallel, alternative, etc.).
4140
4141
4142
4143
4144
4145
4146 Crispin Standards Track [Page 74]
4147
4148 RFC 3501 IMAPv4 March 2003
4149
4150
4151 For example, a two part message consisting of a text and a
4152 BASE64-encoded text attachment can have a body structure of:
4153 (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152
4154 23)("TEXT" "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff")
4155 "<960723163407.20117h@cac.washington.edu>" "Compiler diff"
4156 "BASE64" 4554 73) "MIXED")
4157
4158 Extension data follows the multipart subtype. Extension data
4159 is never returned with the BODY fetch, but can be returned with
4160 a BODYSTRUCTURE fetch. Extension data, if present, MUST be in
4161 the defined order. The extension data of a multipart body part
4162 are in the following order:
4163
4164 body parameter parenthesized list
4165 A parenthesized list of attribute/value pairs [e.g., ("foo"
4166 "bar" "baz" "rag") where "bar" is the value of "foo", and
4167 "rag" is the value of "baz"] as defined in [MIME-IMB].
4168
4169 body disposition
4170 A parenthesized list, consisting of a disposition type
4171 string, followed by a parenthesized list of disposition
4172 attribute/value pairs as defined in [DISPOSITION].
4173
4174 body language
4175 A string or parenthesized list giving the body language
4176 value as defined in [LANGUAGE-TAGS].
4177
4178 body location
4179 A string list giving the body content URI as defined in
4180 [LOCATION].
4181
4182 Any following extension data are not yet defined in this
4183 version of the protocol. Such extension data can consist of
4184 zero or more NILs, strings, numbers, or potentially nested
4185 parenthesized lists of such data. Client implementations that
4186 do a BODYSTRUCTURE fetch MUST be prepared to accept such
4187 extension data. Server implementations MUST NOT send such
4188 extension data until it has been defined by a revision of this
4189 protocol.
4190
4191 The basic fields of a non-multipart body part are in the
4192 following order:
4193
4194 body type
4195 A string giving the content media type name as defined in
4196 [MIME-IMB].
4197
4198
4199
4200
4201
4202 Crispin Standards Track [Page 75]
4203
4204 RFC 3501 IMAPv4 March 2003
4205
4206
4207 body subtype
4208 A string giving the content subtype name as defined in
4209 [MIME-IMB].
4210
4211 body parameter parenthesized list
4212 A parenthesized list of attribute/value pairs [e.g., ("foo"
4213 "bar" "baz" "rag") where "bar" is the value of "foo" and
4214 "rag" is the value of "baz"] as defined in [MIME-IMB].
4215
4216 body id
4217 A string giving the content id as defined in [MIME-IMB].
4218
4219 body description
4220 A string giving the content description as defined in
4221 [MIME-IMB].
4222
4223 body encoding
4224 A string giving the content transfer encoding as defined in
4225 [MIME-IMB].
4226
4227 body size
4228 A number giving the size of the body in octets. Note that
4229 this size is the size in its transfer encoding and not the
4230 resulting size after any decoding.
4231
4232 A body type of type MESSAGE and subtype RFC822 contains,
4233 immediately after the basic fields, the envelope structure,
4234 body structure, and size in text lines of the encapsulated
4235 message.
4236
4237 A body type of type TEXT contains, immediately after the basic
4238 fields, the size of the body in text lines. Note that this
4239 size is the size in its content transfer encoding and not the
4240 resulting size after any decoding.
4241
4242 Extension data follows the basic fields and the type-specific
4243 fields listed above. Extension data is never returned with the
4244 BODY fetch, but can be returned with a BODYSTRUCTURE fetch.
4245 Extension data, if present, MUST be in the defined order.
4246
4247 The extension data of a non-multipart body part are in the
4248 following order:
4249
4250 body MD5
4251 A string giving the body MD5 value as defined in [MD5].
4252
4253
4254
4255
4256
4257
4258 Crispin Standards Track [Page 76]
4259
4260 RFC 3501 IMAPv4 March 2003
4261
4262
4263 body disposition
4264 A parenthesized list with the same content and function as
4265 the body disposition for a multipart body part.
4266
4267 body language
4268 A string or parenthesized list giving the body language
4269 value as defined in [LANGUAGE-TAGS].
4270
4271 body location
4272 A string list giving the body content URI as defined in
4273 [LOCATION].
4274
4275 Any following extension data are not yet defined in this
4276 version of the protocol, and would be as described above under
4277 multipart extension data.
4278
4279 ENVELOPE
4280 A parenthesized list that describes the envelope structure of a
4281 message. This is computed by the server by parsing the
4282 [RFC-2822] header into the component parts, defaulting various
4283 fields as necessary.
4284
4285 The fields of the envelope structure are in the following
4286 order: date, subject, from, sender, reply-to, to, cc, bcc,
4287 in-reply-to, and message-id. The date, subject, in-reply-to,
4288 and message-id fields are strings. The from, sender, reply-to,
4289 to, cc, and bcc fields are parenthesized lists of address
4290 structures.
4291
4292 An address structure is a parenthesized list that describes an
4293 electronic mail address. The fields of an address structure
4294 are in the following order: personal name, [SMTP]
4295 at-domain-list (source route), mailbox name, and host name.
4296
4297 [RFC-2822] group syntax is indicated by a special form of
4298 address structure in which the host name field is NIL. If the
4299 mailbox name field is also NIL, this is an end of group marker
4300 (semi-colon in RFC 822 syntax). If the mailbox name field is
4301 non-NIL, this is a start of group marker, and the mailbox name
4302 field holds the group name phrase.
4303
4304 If the Date, Subject, In-Reply-To, and Message-ID header lines
4305 are absent in the [RFC-2822] header, the corresponding member
4306 of the envelope is NIL; if these header lines are present but
4307 empty the corresponding member of the envelope is the empty
4308 string.
4309
4310
4311
4312
4313
4314 Crispin Standards Track [Page 77]
4315
4316 RFC 3501 IMAPv4 March 2003
4317
4318
4319 Note: some servers may return a NIL envelope member in the
4320 "present but empty" case. Clients SHOULD treat NIL and
4321 empty string as identical.
4322
4323 Note: [RFC-2822] requires that all messages have a valid
4324 Date header. Therefore, the date member in the envelope can
4325 not be NIL or the empty string.
4326
4327 Note: [RFC-2822] requires that the In-Reply-To and
4328 Message-ID headers, if present, have non-empty content.
4329 Therefore, the in-reply-to and message-id members in the
4330 envelope can not be the empty string.
4331
4332 If the From, To, cc, and bcc header lines are absent in the
4333 [RFC-2822] header, or are present but empty, the corresponding
4334 member of the envelope is NIL.
4335
4336 If the Sender or Reply-To lines are absent in the [RFC-2822]
4337 header, or are present but empty, the server sets the
4338 corresponding member of the envelope to be the same value as
4339 the from member (the client is not expected to know to do
4340 this).
4341
4342 Note: [RFC-2822] requires that all messages have a valid
4343 From header. Therefore, the from, sender, and reply-to
4344 members in the envelope can not be NIL.
4345
4346 FLAGS
4347 A parenthesized list of flags that are set for this message.
4348
4349 INTERNALDATE
4350 A string representing the internal date of the message.
4351
4352 RFC822
4353 Equivalent to BODY[].
4354
4355 RFC822.HEADER
4356 Equivalent to BODY[HEADER]. Note that this did not result in
4357 \Seen being set, because RFC822.HEADER response data occurs as
4358 a result of a FETCH of RFC822.HEADER. BODY[HEADER] response
4359 data occurs as a result of a FETCH of BODY[HEADER] (which sets
4360 \Seen) or BODY.PEEK[HEADER] (which does not set \Seen).
4361
4362 RFC822.SIZE
4363 A number expressing the [RFC-2822] size of the message.
4364
4365
4366
4367
4368
4369
4370 Crispin Standards Track [Page 78]
4371
4372 RFC 3501 IMAPv4 March 2003
4373
4374
4375 RFC822.TEXT
4376 Equivalent to BODY[TEXT].
4377
4378 UID
4379 A number expressing the unique identifier of the message.
4380
4381
4382 Example: S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827)
4383
4384
4385 7.5. Server Responses - Command Continuation Request
4386
4387 The command continuation request response is indicated by a "+" token
4388 instead of a tag. This form of response indicates that the server is
4389 ready to accept the continuation of a command from the client. The
4390 remainder of this response is a line of text.
4391
4392 This response is used in the AUTHENTICATE command to transmit server
4393 data to the client, and request additional client data. This
4394 response is also used if an argument to any command is a literal.
4395
4396 The client is not permitted to send the octets of the literal unless
4397 the server indicates that it is expected. This permits the server to
4398 process commands and reject errors on a line-by-line basis. The
4399 remainder of the command, including the CRLF that terminates a
4400 command, follows the octets of the literal. If there are any
4401 additional command arguments, the literal octets are followed by a
4402 space and those arguments.
4403
4404 Example: C: A001 LOGIN {11}
4405 S: + Ready for additional command text
4406 C: FRED FOOBAR {7}
4407 S: + Ready for additional command text
4408 C: fat man
4409 S: A001 OK LOGIN completed
4410 C: A044 BLURDYBLOOP {102856}
4411 S: A044 BAD No such command as "BLURDYBLOOP"
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426 Crispin Standards Track [Page 79]
4427
4428 RFC 3501 IMAPv4 March 2003
4429
4430
4431 8. Sample IMAP4rev1 connection
4432
4433 The following is a transcript of an IMAP4rev1 connection. A long
4434 line in this sample is broken for editorial clarity.
4435
4436 S: * OK IMAP4rev1 Service Ready
4437 C: a001 login mrc secret
4438 S: a001 OK LOGIN completed
4439 C: a002 select inbox
4440 S: * 18 EXISTS
4441 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
4442 S: * 2 RECENT
4443 S: * OK [UNSEEN 17] Message 17 is the first unseen message
4444 S: * OK [UIDVALIDITY 3857529045] UIDs valid
4445 S: a002 OK [READ-WRITE] SELECT completed
4446 C: a003 fetch 12 full
4447 S: * 12 FETCH (FLAGS (\Seen) INTERNALDATE "17-Jul-1996 02:44:25 -0700"
4448 RFC822.SIZE 4286 ENVELOPE ("Wed, 17 Jul 1996 02:23:25 -0700 (PDT)"
4449 "IMAP4rev1 WG mtg summary and minutes"
4450 (("Terry Gray" NIL "gray" "cac.washington.edu"))
4451 (("Terry Gray" NIL "gray" "cac.washington.edu"))
4452 (("Terry Gray" NIL "gray" "cac.washington.edu"))
4453 ((NIL NIL "imap" "cac.washington.edu"))
4454 ((NIL NIL "minutes" "CNRI.Reston.VA.US")
4455 ("John Klensin" NIL "KLENSIN" "MIT.EDU")) NIL NIL
4456 "<B27397-0100000@cac.washington.edu>")
4457 BODY ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 3028
4458 92))
4459 S: a003 OK FETCH completed
4460 C: a004 fetch 12 body[header]
4461 S: * 12 FETCH (BODY[HEADER] {342}
4462 S: Date: Wed, 17 Jul 1996 02:23:25 -0700 (PDT)
4463 S: From: Terry Gray <gray@cac.washington.edu>
4464 S: Subject: IMAP4rev1 WG mtg summary and minutes
4465 S: To: imap@cac.washington.edu
4466 S: cc: minutes@CNRI.Reston.VA.US, John Klensin <KLENSIN@MIT.EDU>
4467 S: Message-Id: <B27397-0100000@cac.washington.edu>
4468 S: MIME-Version: 1.0
4469 S: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
4470 S:
4471 S: )
4472 S: a004 OK FETCH completed
4473 C: a005 store 12 +flags \deleted
4474 S: * 12 FETCH (FLAGS (\Seen \Deleted))
4475 S: a005 OK +FLAGS completed
4476 C: a006 logout
4477 S: * BYE IMAP4rev1 server terminating connection
4478 S: a006 OK LOGOUT completed
4479
4480
4481
4482 Crispin Standards Track [Page 80]
4483
4484 RFC 3501 IMAPv4 March 2003
4485
4486
4487 9. Formal Syntax
4488
4489 The following syntax specification uses the Augmented Backus-Naur
4490 Form (ABNF) notation as specified in [ABNF].
4491
4492 In the case of alternative or optional rules in which a later rule
4493 overlaps an earlier rule, the rule which is listed earlier MUST take
4494 priority. For example, "\Seen" when parsed as a flag is the \Seen
4495 flag name and not a flag-extension, even though "\Seen" can be parsed
4496 as a flag-extension. Some, but not all, instances of this rule are
4497 noted below.
4498
4499 Note: [ABNF] rules MUST be followed strictly; in
4500 particular:
4501
4502 (1) Except as noted otherwise, all alphabetic characters
4503 are case-insensitive. The use of upper or lower case
4504 characters to define token strings is for editorial clarity
4505 only. Implementations MUST accept these strings in a
4506 case-insensitive fashion.
4507
4508 (2) In all cases, SP refers to exactly one space. It is
4509 NOT permitted to substitute TAB, insert additional spaces,
4510 or otherwise treat SP as being equivalent to LWSP.
4511
4512 (3) The ASCII NUL character, %x00, MUST NOT be used at any
4513 time.
4514
4515 address = "(" addr-name SP addr-adl SP addr-mailbox SP
4516 addr-host ")"
4517
4518 addr-adl = nstring
4519 ; Holds route from [RFC-2822] route-addr if
4520 ; non-NIL
4521
4522 addr-host = nstring
4523 ; NIL indicates [RFC-2822] group syntax.
4524 ; Otherwise, holds [RFC-2822] domain name
4525
4526 addr-mailbox = nstring
4527 ; NIL indicates end of [RFC-2822] group; if
4528 ; non-NIL and addr-host is NIL, holds
4529 ; [RFC-2822] group name.
4530 ; Otherwise, holds [RFC-2822] local-part
4531 ; after removing [RFC-2822] quoting
4532
4533
4534
4535
4536
4537
4538 Crispin Standards Track [Page 81]
4539
4540 RFC 3501 IMAPv4 March 2003
4541
4542
4543 addr-name = nstring
4544 ; If non-NIL, holds phrase from [RFC-2822]
4545 ; mailbox after removing [RFC-2822] quoting
4546
4547 append = "APPEND" SP mailbox [SP flag-list] [SP date-time] SP
4548 literal
4549
4550 astring = 1*ASTRING-CHAR / string
4551
4552 ASTRING-CHAR = ATOM-CHAR / resp-specials
4553
4554 atom = 1*ATOM-CHAR
4555
4556 ATOM-CHAR = <any CHAR except atom-specials>
4557
4558 atom-specials = "(" / ")" / "{" / SP / CTL / list-wildcards /
4559 quoted-specials / resp-specials
4560
4561 authenticate = "AUTHENTICATE" SP auth-type *(CRLF base64)
4562
4563 auth-type = atom
4564 ; Defined by [SASL]
4565
4566 base64 = *(4base64-char) [base64-terminal]
4567
4568 base64-char = ALPHA / DIGIT / "+" / "/"
4569 ; Case-sensitive
4570
4571 base64-terminal = (2base64-char "==") / (3base64-char "=")
4572
4573 body = "(" (body-type-1part / body-type-mpart) ")"
4574
4575 body-extension = nstring / number /
4576 "(" body-extension *(SP body-extension) ")"
4577 ; Future expansion. Client implementations
4578 ; MUST accept body-extension fields. Server
4579 ; implementations MUST NOT generate
4580 ; body-extension fields except as defined by
4581 ; future standard or standards-track
4582 ; revisions of this specification.
4583
4584 body-ext-1part = body-fld-md5 [SP body-fld-dsp [SP body-fld-lang
4585 [SP body-fld-loc *(SP body-extension)]]]
4586 ; MUST NOT be returned on non-extensible
4587 ; "BODY" fetch
4588
4589
4590
4591
4592
4593
4594 Crispin Standards Track [Page 82]
4595
4596 RFC 3501 IMAPv4 March 2003
4597
4598
4599 body-ext-mpart = body-fld-param [SP body-fld-dsp [SP body-fld-lang
4600 [SP body-fld-loc *(SP body-extension)]]]
4601 ; MUST NOT be returned on non-extensible
4602 ; "BODY" fetch
4603
4604 body-fields = body-fld-param SP body-fld-id SP body-fld-desc SP
4605 body-fld-enc SP body-fld-octets
4606
4607 body-fld-desc = nstring
4608
4609 body-fld-dsp = "(" string SP body-fld-param ")" / nil
4610
4611 body-fld-enc = (DQUOTE ("7BIT" / "8BIT" / "BINARY" / "BASE64"/
4612 "QUOTED-PRINTABLE") DQUOTE) / string
4613
4614 body-fld-id = nstring
4615
4616 body-fld-lang = nstring / "(" string *(SP string) ")"
4617
4618 body-fld-loc = nstring
4619
4620 body-fld-lines = number
4621
4622 body-fld-md5 = nstring
4623
4624 body-fld-octets = number
4625
4626 body-fld-param = "(" string SP string *(SP string SP string) ")" / nil
4627
4628 body-type-1part = (body-type-basic / body-type-msg / body-type-text)
4629 [SP body-ext-1part]
4630
4631 body-type-basic = media-basic SP body-fields
4632 ; MESSAGE subtype MUST NOT be "RFC822"
4633
4634 body-type-mpart = 1*body SP media-subtype
4635 [SP body-ext-mpart]
4636
4637 body-type-msg = media-message SP body-fields SP envelope
4638 SP body SP body-fld-lines
4639
4640 body-type-text = media-text SP body-fields SP body-fld-lines
4641
4642 capability = ("AUTH=" auth-type) / atom
4643 ; New capabilities MUST begin with "X" or be
4644 ; registered with IANA as standard or
4645 ; standards-track
4646
4647
4648
4649
4650 Crispin Standards Track [Page 83]
4651
4652 RFC 3501 IMAPv4 March 2003
4653
4654
4655 capability-data = "CAPABILITY" *(SP capability) SP "IMAP4rev1"
4656 *(SP capability)
4657 ; Servers MUST implement the STARTTLS, AUTH=PLAIN,
4658 ; and LOGINDISABLED capabilities
4659 ; Servers which offer RFC 1730 compatibility MUST
4660 ; list "IMAP4" as the first capability.
4661
4662 CHAR8 = %x01-ff
4663 ; any OCTET except NUL, %x00
4664
4665 command = tag SP (command-any / command-auth / command-nonauth /
4666 command-select) CRLF
4667 ; Modal based on state
4668
4669 command-any = "CAPABILITY" / "LOGOUT" / "NOOP" / x-command
4670 ; Valid in all states
4671
4672 command-auth = append / create / delete / examine / list / lsub /
4673 rename / select / status / subscribe / unsubscribe
4674 ; Valid only in Authenticated or Selected state
4675
4676 command-nonauth = login / authenticate / "STARTTLS"
4677 ; Valid only when in Not Authenticated state
4678
4679 command-select = "CHECK" / "CLOSE" / "EXPUNGE" / copy / fetch / store /
4680 uid / search
4681 ; Valid only when in Selected state
4682
4683 continue-req = "+" SP (resp-text / base64) CRLF
4684
4685 copy = "COPY" SP sequence-set SP mailbox
4686
4687 create = "CREATE" SP mailbox
4688 ; Use of INBOX gives a NO error
4689
4690 date = date-text / DQUOTE date-text DQUOTE
4691
4692 date-day = 1*2DIGIT
4693 ; Day of month
4694
4695 date-day-fixed = (SP DIGIT) / 2DIGIT
4696 ; Fixed-format version of date-day
4697
4698 date-month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
4699 "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
4700
4701 date-text = date-day "-" date-month "-" date-year
4702
4703
4704
4705
4706 Crispin Standards Track [Page 84]
4707
4708 RFC 3501 IMAPv4 March 2003
4709
4710
4711 date-year = 4DIGIT
4712
4713 date-time = DQUOTE date-day-fixed "-" date-month "-" date-year
4714 SP time SP zone DQUOTE
4715
4716 delete = "DELETE" SP mailbox
4717 ; Use of INBOX gives a NO error
4718
4719 digit-nz = %x31-39
4720 ; 1-9
4721
4722 envelope = "(" env-date SP env-subject SP env-from SP
4723 env-sender SP env-reply-to SP env-to SP env-cc SP
4724 env-bcc SP env-in-reply-to SP env-message-id ")"
4725
4726 env-bcc = "(" 1*address ")" / nil
4727
4728 env-cc = "(" 1*address ")" / nil
4729
4730 env-date = nstring
4731
4732 env-from = "(" 1*address ")" / nil
4733
4734 env-in-reply-to = nstring
4735
4736 env-message-id = nstring
4737
4738 env-reply-to = "(" 1*address ")" / nil
4739
4740 env-sender = "(" 1*address ")" / nil
4741
4742 env-subject = nstring
4743
4744 env-to = "(" 1*address ")" / nil
4745
4746 examine = "EXAMINE" SP mailbox
4747
4748 fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" / "FAST" /
4749 fetch-att / "(" fetch-att *(SP fetch-att) ")")
4750
4751 fetch-att = "ENVELOPE" / "FLAGS" / "INTERNALDATE" /
4752 "RFC822" [".HEADER" / ".SIZE" / ".TEXT"] /
4753 "BODY" ["STRUCTURE"] / "UID" /
4754 "BODY" section ["<" number "." nz-number ">"] /
4755 "BODY.PEEK" section ["<" number "." nz-number ">"]
4756
4757
4758
4759
4760
4761
4762 Crispin Standards Track [Page 85]
4763
4764 RFC 3501 IMAPv4 March 2003
4765
4766
4767 flag = "\Answered" / "\Flagged" / "\Deleted" /
4768 "\Seen" / "\Draft" / flag-keyword / flag-extension
4769 ; Does not include "\Recent"
4770
4771 flag-extension = "\" atom
4772 ; Future expansion. Client implementations
4773 ; MUST accept flag-extension flags. Server
4774 ; implementations MUST NOT generate
4775 ; flag-extension flags except as defined by
4776 ; future standard or standards-track
4777 ; revisions of this specification.
4778
4779 flag-fetch = flag / "\Recent"
4780
4781 flag-keyword = atom
4782
4783 flag-list = "(" [flag *(SP flag)] ")"
4784
4785 flag-perm = flag / "\*"
4786
4787 greeting = "*" SP (resp-cond-auth / resp-cond-bye) CRLF
4788
4789 header-fld-name = astring
4790
4791 header-list = "(" header-fld-name *(SP header-fld-name) ")"
4792
4793 list = "LIST" SP mailbox SP list-mailbox
4794
4795 list-mailbox = 1*list-char / string
4796
4797 list-char = ATOM-CHAR / list-wildcards / resp-specials
4798
4799 list-wildcards = "%" / "*"
4800
4801 literal = "{" number "}" CRLF *CHAR8
4802 ; Number represents the number of CHAR8s
4803
4804 login = "LOGIN" SP userid SP password
4805
4806 lsub = "LSUB" SP mailbox SP list-mailbox
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818 Crispin Standards Track [Page 86]
4819
4820 RFC 3501 IMAPv4 March 2003
4821
4822
4823 mailbox = "INBOX" / astring
4824 ; INBOX is case-insensitive. All case variants of
4825 ; INBOX (e.g., "iNbOx") MUST be interpreted as INBOX
4826 ; not as an astring. An astring which consists of
4827 ; the case-insensitive sequence "I" "N" "B" "O" "X"
4828 ; is considered to be INBOX and not an astring.
4829 ; Refer to section 5.1 for further
4830 ; semantic details of mailbox names.
4831
4832 mailbox-data = "FLAGS" SP flag-list / "LIST" SP mailbox-list /
4833 "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) /
4834 "STATUS" SP mailbox SP "(" [status-att-list] ")" /
4835 number SP "EXISTS" / number SP "RECENT"
4836
4837 mailbox-list = "(" [mbx-list-flags] ")" SP
4838 (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox
4839
4840 mbx-list-flags = *(mbx-list-oflag SP) mbx-list-sflag
4841 *(SP mbx-list-oflag) /
4842 mbx-list-oflag *(SP mbx-list-oflag)
4843
4844 mbx-list-oflag = "\Noinferiors" / flag-extension
4845 ; Other flags; multiple possible per LIST response
4846
4847 mbx-list-sflag = "\Noselect" / "\Marked" / "\Unmarked"
4848 ; Selectability flags; only one per LIST response
4849
4850 media-basic = ((DQUOTE ("APPLICATION" / "AUDIO" / "IMAGE" /
4851 "MESSAGE" / "VIDEO") DQUOTE) / string) SP
4852 media-subtype
4853 ; Defined in [MIME-IMT]
4854
4855 media-message = DQUOTE "MESSAGE" DQUOTE SP DQUOTE "RFC822" DQUOTE
4856 ; Defined in [MIME-IMT]
4857
4858 media-subtype = string
4859 ; Defined in [MIME-IMT]
4860
4861 media-text = DQUOTE "TEXT" DQUOTE SP media-subtype
4862 ; Defined in [MIME-IMT]
4863
4864 message-data = nz-number SP ("EXPUNGE" / ("FETCH" SP msg-att))
4865
4866 msg-att = "(" (msg-att-dynamic / msg-att-static)
4867 *(SP (msg-att-dynamic / msg-att-static)) ")"
4868
4869 msg-att-dynamic = "FLAGS" SP "(" [flag-fetch *(SP flag-fetch)] ")"
4870 ; MAY change for a message
4871
4872
4873
4874 Crispin Standards Track [Page 87]
4875
4876 RFC 3501 IMAPv4 March 2003
4877
4878
4879 msg-att-static = "ENVELOPE" SP envelope / "INTERNALDATE" SP date-time /
4880 "RFC822" [".HEADER" / ".TEXT"] SP nstring /
4881 "RFC822.SIZE" SP number /
4882 "BODY" ["STRUCTURE"] SP body /
4883 "BODY" section ["<" number ">"] SP nstring /
4884 "UID" SP uniqueid
4885 ; MUST NOT change for a message
4886
4887 nil = "NIL"
4888
4889 nstring = string / nil
4890
4891 number = 1*DIGIT
4892 ; Unsigned 32-bit integer
4893 ; (0 <= n < 4,294,967,296)
4894
4895 nz-number = digit-nz *DIGIT
4896 ; Non-zero unsigned 32-bit integer
4897 ; (0 < n < 4,294,967,296)
4898
4899 password = astring
4900
4901 quoted = DQUOTE *QUOTED-CHAR DQUOTE
4902
4903 QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> /
4904 "\" quoted-specials
4905
4906 quoted-specials = DQUOTE / "\"
4907
4908 rename = "RENAME" SP mailbox SP mailbox
4909 ; Use of INBOX as a destination gives a NO error
4910
4911 response = *(continue-req / response-data) response-done
4912
4913 response-data = "*" SP (resp-cond-state / resp-cond-bye /
4914 mailbox-data / message-data / capability-data) CRLF
4915
4916 response-done = response-tagged / response-fatal
4917
4918 response-fatal = "*" SP resp-cond-bye CRLF
4919 ; Server closes connection immediately
4920
4921 response-tagged = tag SP resp-cond-state CRLF
4922
4923 resp-cond-auth = ("OK" / "PREAUTH") SP resp-text
4924 ; Authentication condition
4925
4926
4927
4928
4929
4930 Crispin Standards Track [Page 88]
4931
4932 RFC 3501 IMAPv4 March 2003
4933
4934
4935 resp-cond-bye = "BYE" SP resp-text
4936
4937 resp-cond-state = ("OK" / "NO" / "BAD") SP resp-text
4938 ; Status condition
4939
4940 resp-specials = "]"
4941
4942 resp-text = ["[" resp-text-code "]" SP] text
4943
4944 resp-text-code = "ALERT" /
4945 "BADCHARSET" [SP "(" astring *(SP astring) ")" ] /
4946 capability-data / "PARSE" /
4947 "PERMANENTFLAGS" SP "("
4948 [flag-perm *(SP flag-perm)] ")" /
4949 "READ-ONLY" / "READ-WRITE" / "TRYCREATE" /
4950 "UIDNEXT" SP nz-number / "UIDVALIDITY" SP nz-number /
4951 "UNSEEN" SP nz-number /
4952 atom [SP 1*<any TEXT-CHAR except "]">]
4953
4954 search = "SEARCH" [SP "CHARSET" SP astring] 1*(SP search-key)
4955 ; CHARSET argument to MUST be registered with IANA
4956
4957 search-key = "ALL" / "ANSWERED" / "BCC" SP astring /
4958 "BEFORE" SP date / "BODY" SP astring /
4959 "CC" SP astring / "DELETED" / "FLAGGED" /
4960 "FROM" SP astring / "KEYWORD" SP flag-keyword /
4961 "NEW" / "OLD" / "ON" SP date / "RECENT" / "SEEN" /
4962 "SINCE" SP date / "SUBJECT" SP astring /
4963 "TEXT" SP astring / "TO" SP astring /
4964 "UNANSWERED" / "UNDELETED" / "UNFLAGGED" /
4965 "UNKEYWORD" SP flag-keyword / "UNSEEN" /
4966 ; Above this line were in [IMAP2]
4967 "DRAFT" / "HEADER" SP header-fld-name SP astring /
4968 "LARGER" SP number / "NOT" SP search-key /
4969 "OR" SP search-key SP search-key /
4970 "SENTBEFORE" SP date / "SENTON" SP date /
4971 "SENTSINCE" SP date / "SMALLER" SP number /
4972 "UID" SP sequence-set / "UNDRAFT" / sequence-set /
4973 "(" search-key *(SP search-key) ")"
4974
4975 section = "[" [section-spec] "]"
4976
4977 section-msgtext = "HEADER" / "HEADER.FIELDS" [".NOT"] SP header-list /
4978 "TEXT"
4979 ; top-level or MESSAGE/RFC822 part
4980
4981 section-part = nz-number *("." nz-number)
4982 ; body part nesting
4983
4984
4985
4986 Crispin Standards Track [Page 89]
4987
4988 RFC 3501 IMAPv4 March 2003
4989
4990
4991 section-spec = section-msgtext / (section-part ["." section-text])
4992
4993 section-text = section-msgtext / "MIME"
4994 ; text other than actual body part (headers, etc.)
4995
4996 select = "SELECT" SP mailbox
4997
4998 seq-number = nz-number / "*"
4999 ; message sequence number (COPY, FETCH, STORE
5000 ; commands) or unique identifier (UID COPY,
5001 ; UID FETCH, UID STORE commands).
5002 ; * represents the largest number in use. In
5003 ; the case of message sequence numbers, it is
5004 ; the number of messages in a non-empty mailbox.
5005 ; In the case of unique identifiers, it is the
5006 ; unique identifier of the last message in the
5007 ; mailbox or, if the mailbox is empty, the
5008 ; mailbox's current UIDNEXT value.
5009 ; The server should respond with a tagged BAD
5010 ; response to a command that uses a message
5011 ; sequence number greater than the number of
5012 ; messages in the selected mailbox. This
5013 ; includes "*" if the selected mailbox is empty.
5014
5015 seq-range = seq-number ":" seq-number
5016 ; two seq-number values and all values between
5017 ; these two regardless of order.
5018 ; Example: 2:4 and 4:2 are equivalent and indicate
5019 ; values 2, 3, and 4.
5020 ; Example: a unique identifier sequence range of
5021 ; 3291:* includes the UID of the last message in
5022 ; the mailbox, even if that value is less than 3291.
5023
5024 sequence-set = (seq-number / seq-range) *("," sequence-set)
5025 ; set of seq-number values, regardless of order.
5026 ; Servers MAY coalesce overlaps and/or execute the
5027 ; sequence in any order.
5028 ; Example: a message sequence number set of
5029 ; 2,4:7,9,12:* for a mailbox with 15 messages is
5030 ; equivalent to 2,4,5,6,7,9,12,13,14,15
5031 ; Example: a message sequence number set of *:4,5:7
5032 ; for a mailbox with 10 messages is equivalent to
5033 ; 10,9,8,7,6,5,4,5,6,7 and MAY be reordered and
5034 ; overlap coalesced to be 4,5,6,7,8,9,10.
5035
5036 status = "STATUS" SP mailbox SP
5037 "(" status-att *(SP status-att) ")"
5038
5039
5040
5041
5042 Crispin Standards Track [Page 90]
5043
5044 RFC 3501 IMAPv4 March 2003
5045
5046
5047 status-att = "MESSAGES" / "RECENT" / "UIDNEXT" / "UIDVALIDITY" /
5048 "UNSEEN"
5049
5050 status-att-list = status-att SP number *(SP status-att SP number)
5051
5052 store = "STORE" SP sequence-set SP store-att-flags
5053
5054 store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP
5055 (flag-list / (flag *(SP flag)))
5056
5057 string = quoted / literal
5058
5059 subscribe = "SUBSCRIBE" SP mailbox
5060
5061 tag = 1*<any ASTRING-CHAR except "+">
5062
5063 text = 1*TEXT-CHAR
5064
5065 TEXT-CHAR = <any CHAR except CR and LF>
5066
5067 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
5068 ; Hours minutes seconds
5069
5070 uid = "UID" SP (copy / fetch / search / store)
5071 ; Unique identifiers used instead of message
5072 ; sequence numbers
5073
5074 uniqueid = nz-number
5075 ; Strictly ascending
5076
5077 unsubscribe = "UNSUBSCRIBE" SP mailbox
5078
5079 userid = astring
5080
5081 x-command = "X" atom <experimental command arguments>
5082
5083 zone = ("+" / "-") 4DIGIT
5084 ; Signed four-digit value of hhmm representing
5085 ; hours and minutes east of Greenwich (that is,
5086 ; the amount that the given time differs from
5087 ; Universal Time). Subtracting the timezone
5088 ; from the given time will give the UT form.
5089 ; The Universal Time zone is "+0000".
5090
5091
5092
5093
5094
5095
5096
5097
5098 Crispin Standards Track [Page 91]
5099
5100 RFC 3501 IMAPv4 March 2003
5101
5102
5103 10. Author's Note
5104
5105 This document is a revision or rewrite of earlier documents, and
5106 supercedes the protocol specification in those documents: RFC 2060,
5107 RFC 1730, unpublished IMAP2bis.TXT document, RFC 1176, and RFC 1064.
5108
5109 11. Security Considerations
5110
5111 IMAP4rev1 protocol transactions, including electronic mail data, are
5112 sent in the clear over the network unless protection from snooping is
5113 negotiated. This can be accomplished either by the use of STARTTLS,
5114 negotiated privacy protection in the AUTHENTICATE command, or some
5115 other protection mechanism.
5116
5117 11.1. STARTTLS Security Considerations
5118
5119 The specification of the STARTTLS command and LOGINDISABLED
5120 capability in this document replaces that in [IMAP-TLS]. [IMAP-TLS]
5121 remains normative for the PLAIN [SASL] authenticator.
5122
5123 IMAP client and server implementations MUST implement the
5124 TLS_RSA_WITH_RC4_128_MD5 [TLS] cipher suite, and SHOULD implement the
5125 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher suite. This is
5126 important as it assures that any two compliant implementations can be
5127 configured to interoperate. All other cipher suites are OPTIONAL.
5128 Note that this is a change from section 2.1 of [IMAP-TLS].
5129
5130 During the [TLS] negotiation, the client MUST check its understanding
5131 of the server hostname against the server's identity as presented in
5132 the server Certificate message, in order to prevent man-in-the-middle
5133 attacks. If the match fails, the client SHOULD either ask for
5134 explicit user confirmation, or terminate the connection and indicate
5135 that the server's identity is suspect. Matching is performed
5136 according to these rules:
5137
5138 The client MUST use the server hostname it used to open the
5139 connection as the value to compare against the server name
5140 as expressed in the server certificate. The client MUST
5141 NOT use any form of the server hostname derived from an
5142 insecure remote source (e.g., insecure DNS lookup). CNAME
5143 canonicalization is not done.
5144
5145 If a subjectAltName extension of type dNSName is present in
5146 the certificate, it SHOULD be used as the source of the
5147 server's identity.
5148
5149 Matching is case-insensitive.
5150
5151
5152
5153
5154 Crispin Standards Track [Page 92]
5155
5156 RFC 3501 IMAPv4 March 2003
5157
5158
5159 A "*" wildcard character MAY be used as the left-most name
5160 component in the certificate. For example, *.example.com
5161 would match a.example.com, foo.example.com, etc. but would
5162 not match example.com.
5163
5164 If the certificate contains multiple names (e.g., more than
5165 one dNSName field), then a match with any one of the fields
5166 is considered acceptable.
5167
5168 Both the client and server MUST check the result of the STARTTLS
5169 command and subsequent [TLS] negotiation to see whether acceptable
5170 authentication or privacy was achieved.
5171
5172 11.2. Other Security Considerations
5173
5174 A server error message for an AUTHENTICATE command which fails due to
5175 invalid credentials SHOULD NOT detail why the credentials are
5176 invalid.
5177
5178 Use of the LOGIN command sends passwords in the clear. This can be
5179 avoided by using the AUTHENTICATE command with a [SASL] mechanism
5180 that does not use plaintext passwords, by first negotiating
5181 encryption via STARTTLS or some other protection mechanism.
5182
5183 A server implementation MUST implement a configuration that, at the
5184 time of authentication, requires:
5185 (1) The STARTTLS command has been negotiated.
5186 OR
5187 (2) Some other mechanism that protects the session from password
5188 snooping has been provided.
5189 OR
5190 (3) The following measures are in place:
5191 (a) The LOGINDISABLED capability is advertised, and [SASL]
5192 mechanisms (such as PLAIN) using plaintext passwords are NOT
5193 advertised in the CAPABILITY list.
5194 AND
5195 (b) The LOGIN command returns an error even if the password is
5196 correct.
5197 AND
5198 (c) The AUTHENTICATE command returns an error with all [SASL]
5199 mechanisms that use plaintext passwords, even if the password
5200 is correct.
5201
5202 A server error message for a failing LOGIN command SHOULD NOT specify
5203 that the user name, as opposed to the password, is invalid.
5204
5205 A server SHOULD have mechanisms in place to limit or delay failed
5206 AUTHENTICATE/LOGIN attempts.
5207
5208
5209
5210 Crispin Standards Track [Page 93]
5211
5212 RFC 3501 IMAPv4 March 2003
5213
5214
5215 Additional security considerations are discussed in the section
5216 discussing the AUTHENTICATE and LOGIN commands.
5217
5218 12. IANA Considerations
5219
5220 IMAP4 capabilities are registered by publishing a standards track or
5221 IESG approved experimental RFC. The registry is currently located
5222 at:
5223
5224 http://www.iana.org/assignments/imap4-capabilities
5225
5226 As this specification revises the STARTTLS and LOGINDISABLED
5227 extensions previously defined in [IMAP-TLS], the registry will be
5228 updated accordingly.
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266 Crispin Standards Track [Page 94]
5267
5268 RFC 3501 IMAPv4 March 2003
5269
5270
5271 Appendices
5272
5273 A. Normative References
5274
5275 The following documents contain definitions or specifications that
5276 are necessary to understand this document properly:
5277 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for
5278 Syntax Specifications: ABNF", RFC 2234,
5279 November 1997.
5280
5281 [ANONYMOUS] Newman, C., "Anonymous SASL Mechanism", RFC
5282 2245, November 1997.
5283
5284 [CHARSET] Freed, N. and J. Postel, "IANA Character Set
5285 Registration Procedures", RFC 2978, October
5286 2000.
5287
5288 [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest
5289 Authentication as a SASL Mechanism", RFC 2831,
5290 May 2000.
5291
5292 [DISPOSITION] Troost, R., Dorner, S. and K. Moore,
5293 "Communicating Presentation Information in
5294 Internet Messages: The Content-Disposition
5295 Header", RFC 2183, August 1997.
5296
5297 [IMAP-TLS] Newman, C., "Using TLS with IMAP, POP3 and
5298 ACAP", RFC 2595, June 1999.
5299
5300 [KEYWORDS] Bradner, S., "Key words for use in RFCs to
5301 Indicate Requirement Levels", BCP 14, RFC 2119,
5302 March 1997.
5303
5304 [LANGUAGE-TAGS] Alvestrand, H., "Tags for the Identification of
5305 Languages", BCP 47, RFC 3066, January 2001.
5306
5307 [LOCATION] Palme, J., Hopmann, A. and N. Shelness, "MIME
5308 Encapsulation of Aggregate Documents, such as
5309 HTML (MHTML)", RFC 2557, March 1999.
5310
5311 [MD5] Myers, J. and M. Rose, "The Content-MD5 Header
5312 Field", RFC 1864, October 1995.
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322 Crispin Standards Track [Page 95]
5323
5324 RFC 3501 IMAPv4 March 2003
5325
5326
5327 [MIME-HDRS] Moore, K., "MIME (Multipurpose Internet Mail
5328 Extensions) Part Three: Message Header
5329 Extensions for Non-ASCII Text", RFC 2047,
5330 November 1996.
5331
5332 [MIME-IMB] Freed, N. and N. Borenstein, "MIME
5333 (Multipurpose Internet Mail Extensions) Part
5334 One: Format of Internet Message Bodies", RFC
5335 2045, November 1996.
5336
5337 [MIME-IMT] Freed, N. and N. Borenstein, "MIME
5338 (Multipurpose Internet Mail Extensions) Part
5339 Two: Media Types", RFC 2046, November 1996.
5340
5341 [RFC-2822] Resnick, P., "Internet Message Format", RFC
5342 2822, April 2001.
5343
5344 [SASL] Myers, J., "Simple Authentication and Security
5345 Layer (SASL)", RFC 2222, October 1997.
5346
5347 [TLS] Dierks, T. and C. Allen, "The TLS Protocol
5348 Version 1.0", RFC 2246, January 1999.
5349
5350 [UTF-7] Goldsmith, D. and M. Davis, "UTF-7: A Mail-Safe
5351 Transformation Format of Unicode", RFC 2152,
5352 May 1997.
5353
5354 The following documents describe quality-of-implementation issues
5355 that should be carefully considered when implementing this protocol:
5356
5357 [IMAP-IMPLEMENTATION] Leiba, B., "IMAP Implementation
5358 Recommendations", RFC 2683, September 1999.
5359
5360 [IMAP-MULTIACCESS] Gahrns, M., "IMAP4 Multi-Accessed Mailbox
5361 Practice", RFC 2180, July 1997.
5362
5363 A.1 Informative References
5364
5365 The following documents describe related protocols:
5366
5367 [IMAP-DISC] Austein, R., "Synchronization Operations for
5368 Disconnected IMAP4 Clients", Work in Progress.
5369
5370 [IMAP-MODEL] Crispin, M., "Distributed Electronic Mail
5371 Models in IMAP4", RFC 1733, December 1994.
5372
5373
5374
5375
5376
5377
5378 Crispin Standards Track [Page 96]
5379
5380 RFC 3501 IMAPv4 March 2003
5381
5382
5383 [ACAP] Newman, C. and J. Myers, "ACAP -- Application
5384 Configuration Access Protocol", RFC 2244,
5385 November 1997.
5386
5387 [SMTP] Klensin, J., "Simple Mail Transfer Protocol",
5388 STD 10, RFC 2821, April 2001.
5389
5390 The following documents are historical or describe historical aspects
5391 of this protocol:
5392
5393 [IMAP-COMPAT] Crispin, M., "IMAP4 Compatibility with
5394 IMAP2bis", RFC 2061, December 1996.
5395
5396 [IMAP-HISTORICAL] Crispin, M., "IMAP4 Compatibility with IMAP2
5397 and IMAP2bis", RFC 1732, December 1994.
5398
5399 [IMAP-OBSOLETE] Crispin, M., "Internet Message Access Protocol
5400 - Obsolete Syntax", RFC 2062, December 1996.
5401
5402 [IMAP2] Crispin, M., "Interactive Mail Access Protocol
5403 - Version 2", RFC 1176, August 1990.
5404
5405 [RFC-822] Crocker, D., "Standard for the Format of ARPA
5406 Internet Text Messages", STD 11, RFC 822,
5407 August 1982.
5408
5409 [RFC-821] Postel, J., "Simple Mail Transfer Protocol",
5410 STD 10, RFC 821, August 1982.
5411
5412 B. Changes from RFC 2060
5413
5414 1) Clarify description of unique identifiers and their semantics.
5415
5416 2) Fix the SELECT description to clarify that UIDVALIDITY is required
5417 in the SELECT and EXAMINE responses.
5418
5419 3) Added an example of a failing search.
5420
5421 4) Correct store-att-flags: "#flag" should be "1#flag".
5422
5423 5) Made search and section rules clearer.
5424
5425 6) Correct the STORE example.
5426
5427 7) Correct "BASE645" misspelling.
5428
5429 8) Remove extraneous close parenthesis in example of two-part message
5430 with text and BASE64 attachment.
5431
5432
5433
5434 Crispin Standards Track [Page 97]
5435
5436 RFC 3501 IMAPv4 March 2003
5437
5438
5439 9) Remove obsolete "MAILBOX" response from mailbox-data.
5440
5441 10) A spurious "<" in the rule for mailbox-data was removed.
5442
5443 11) Add CRLF to continue-req.
5444
5445 12) Specifically exclude "]" from the atom in resp-text-code.
5446
5447 13) Clarify that clients and servers should adhere strictly to the
5448 protocol syntax.
5449
5450 14) Emphasize in 5.2 that EXISTS can not be used to shrink a mailbox.
5451
5452 15) Add NEWNAME to resp-text-code.
5453
5454 16) Clarify that the empty string, not NIL, is used as arguments to
5455 LIST.
5456
5457 17) Clarify that NIL can be returned as a hierarchy delimiter for the
5458 empty string mailbox name argument if the mailbox namespace is flat.
5459
5460 18) Clarify that addr-mailbox and addr-name have RFC-2822 quoting
5461 removed.
5462
5463 19) Update UTF-7 reference.
5464
5465 20) Fix example in 6.3.11.
5466
5467 21) Clarify that non-existent UIDs are ignored.
5468
5469 22) Update DISPOSITION reference.
5470
5471 23) Expand state diagram.
5472
5473 24) Clarify that partial fetch responses are only returned in
5474 response to a partial fetch command.
5475
5476 25) Add UIDNEXT response code. Correct UIDVALIDITY definition
5477 reference.
5478
5479 26) Further clarification of "can" vs. "MAY".
5480
5481 27) Reference RFC-2119.
5482
5483 28) Clarify that superfluous shifts are not permitted in modified
5484 UTF-7.
5485
5486 29) Clarify that there are no implicit shifts in modified UTF-7.
5487
5488
5489
5490 Crispin Standards Track [Page 98]
5491
5492 RFC 3501 IMAPv4 March 2003
5493
5494
5495 30) Clarify that "INBOX" in a mailbox name is always INBOX, even if
5496 it is given as a string.
5497
5498 31) Add missing open parenthesis in media-basic grammar rule.
5499
5500 32) Correct attribute syntax in mailbox-data.
5501
5502 33) Add UIDNEXT to EXAMINE responses.
5503
5504 34) Clarify UNSEEN, PERMANENTFLAGS, UIDVALIDITY, and UIDNEXT
5505 responses in SELECT and EXAMINE. They are required now, but weren't
5506 in older versions.
5507
5508 35) Update references with RFC numbers.
5509
5510 36) Flush text-mime2.
5511
5512 37) Clarify that modified UTF-7 names must be case-sensitive and that
5513 violating the convention should be avoided.
5514
5515 38) Correct UID FETCH example.
5516
5517 39) Clarify UID FETCH, UID STORE, and UID SEARCH vs. untagged EXPUNGE
5518 responses.
5519
5520 40) Clarify the use of the word "convention".
5521
5522 41) Clarify that a command is not "in progress" until it has been
5523 fully received (specifically, that a command is not "in progress"
5524 during command continuation negotiation).
5525
5526 42) Clarify envelope defaulting.
5527
5528 43) Clarify that SP means one and only one space character.
5529
5530 44) Forbid silly states in LIST response.
5531
5532 45) Clarify that the ENVELOPE, INTERNALDATE, RFC822*, BODY*, and UID
5533 for a message is static.
5534
5535 46) Add BADCHARSET response code.
5536
5537 47) Update formal syntax to [ABNF] conventions.
5538
5539 48) Clarify trailing hierarchy delimiter in CREATE semantics.
5540
5541 49) Clarify that the "blank line" is the [RFC-2822] delimiting blank
5542 line.
5543
5544
5545
5546 Crispin Standards Track [Page 99]
5547
5548 RFC 3501 IMAPv4 March 2003
5549
5550
5551 50) Clarify that RENAME should also create hierarchy as needed for
5552 the command to complete.
5553
5554 51) Fix body-ext-mpart to not require language if disposition
5555 present.
5556
5557 52) Clarify the RFC822.HEADER response.
5558
5559 53) Correct missing space after charset astring in search.
5560
5561 54) Correct missing quote for BADCHARSET in resp-text-code.
5562
5563 55) Clarify that ALL, FAST, and FULL preclude any other data items
5564 appearing.
5565
5566 56) Clarify semantics of reference argument in LIST.
5567
5568 57) Clarify that a null string for SEARCH HEADER X-FOO means any
5569 message with a header line with a field-name of X-FOO regardless of
5570 the text of the header.
5571
5572 58) Specifically reserve 8-bit mailbox names for future use as UTF-8.
5573
5574 59) It is not an error for the client to store a flag that is not in
5575 the PERMANENTFLAGS list; however, the server will either ignore the
5576 change or make the change in the session only.
5577
5578 60) Correct/clarify the text regarding superfluous shifts.
5579
5580 61) Correct typographic errors in the "Changes" section.
5581
5582 62) Clarify that STATUS must not be used to check for new messages in
5583 the selected mailbox
5584
5585 63) Clarify LSUB behavior with "%" wildcard.
5586
5587 64) Change AUTHORIZATION to AUTHENTICATE in section 7.5.
5588
5589 65) Clarify description of multipart body type.
5590
5591 66) Clarify that STORE FLAGS does not affect \Recent.
5592
5593 67) Change "west" to "east" in description of timezone.
5594
5595 68) Clarify that commands which break command pipelining must wait
5596 for a completion result response.
5597
5598 69) Clarify that EXAMINE does not affect \Recent.
5599
5600
5601
5602 Crispin Standards Track [Page 100]
5603
5604 RFC 3501 IMAPv4 March 2003
5605
5606
5607 70) Make description of MIME structure consistent.
5608
5609 71) Clarify that date searches disregard the time and timezone of the
5610 INTERNALDATE or Date: header. In other words, "ON 13-APR-2000" means
5611 messages with an INTERNALDATE text which starts with "13-APR-2000",
5612 even if timezone differential from the local timezone is sufficient
5613 to move that INTERNALDATE into the previous or next day.
5614
5615 72) Clarify that the header fetches don't add a blank line if one
5616 isn't in the [RFC-2822] message.
5617
5618 73) Clarify (in discussion of UIDs) that messages are immutable.
5619
5620 74) Add an example of CHARSET searching.
5621
5622 75) Clarify in SEARCH that keywords are a type of flag.
5623
5624 76) Clarify the mandatory nature of the SELECT data responses.
5625
5626 77) Add optional CAPABILITY response code in the initial OK or
5627 PREAUTH.
5628
5629 78) Add note that server can send an untagged CAPABILITY command as
5630 part of the responses to AUTHENTICATE and LOGIN.
5631
5632 79) Remove statement about it being unnecessary to issue a CAPABILITY
5633 command more than once in a connection. That statement is no longer
5634 true.
5635
5636 80) Clarify that untagged EXPUNGE decrements the number of messages
5637 in the mailbox.
5638
5639 81) Fix definition of "body" (concatenation has tighter binding than
5640 alternation).
5641
5642 82) Add a new "Special Notes to Implementors" section with reference
5643 to [IMAP-IMPLEMENTATION].
5644
5645 83) Clarify that an untagged CAPABILITY response to an AUTHENTICATE
5646 command should only be done if a security layer was not negotiated.
5647
5648 84) Change the definition of atom to exclude "]". Update astring to
5649 include "]" for compatibility with the past. Remove resp-text-atom.
5650
5651 85) Remove NEWNAME. It can't work because mailbox names can be
5652 literals and can include "]". Functionality can be addressed via
5653 referrals.
5654
5655
5656
5657
5658 Crispin Standards Track [Page 101]
5659
5660 RFC 3501 IMAPv4 March 2003
5661
5662
5663 86) Move modified UTF-7 rationale in order to have more logical
5664 paragraph flow.
5665
5666 87) Clarify UID uniqueness guarantees with the use of MUST.
5667
5668 88) Note that clients should read response data until the connection
5669 is closed instead of immediately closing on a BYE.
5670
5671 89) Change RFC-822 references to RFC-2822.
5672
5673 90) Clarify that RFC-2822 should be followed instead of RFC-822.
5674
5675 91) Change recommendation of optional automatic capabilities in LOGIN
5676 and AUTHENTICATE to use the CAPABILITY response code in the tagged
5677 OK. This is more interoperable than an unsolicited untagged
5678 CAPABILITY response.
5679
5680 92) STARTTLS and AUTH=PLAIN are mandatory to implement; add
5681 recommendations for other [SASL] mechanisms.
5682
5683 93) Clarify that a "connection" (as opposed to "server" or "command")
5684 is in one of the four states.
5685
5686 94) Clarify that a failed or rejected command does not change state.
5687
5688 95) Split references between normative and informative.
5689
5690 96) Discuss authentication failure issues in security section.
5691
5692 97) Clarify that a data item is not necessarily of only one data
5693 type.
5694
5695 98) Clarify that sequence ranges are independent of order.
5696
5697 99) Change an example to clarify that superfluous shifts in
5698 Modified-UTF7 can not be fixed just by omitting the shift. The
5699 entire string must be recalculated.
5700
5701 100) Change Envelope Structure definition since [RFC-2822] uses
5702 "envelope" to refer to the [SMTP] envelope and not the envelope data
5703 that appears in the [RFC-2822] header.
5704
5705 101) Expand on RFC822.HEADER response data vs. BODY[HEADER].
5706
5707 102) Clarify Logout state semantics, change ASCII art.
5708
5709 103) Security changes to comply with IESG requirements.
5710
5711
5712
5713
5714 Crispin Standards Track [Page 102]
5715
5716 RFC 3501 IMAPv4 March 2003
5717
5718
5719 104) Add definition for body URI.
5720
5721 105) Break sequence range definition into three rules, with rewritten
5722 descriptions for each.
5723
5724 106) Move STARTTLS and LOGINDISABLED here from [IMAP-TLS].
5725
5726 107) Add IANA Considerations section.
5727
5728 108) Clarify valid client assumptions for new message UIDs vs.
5729 UIDNEXT.
5730
5731 109) Clarify that changes to permanentflags affect concurrent
5732 sessions as well as subsequent sessions.
5733
5734 110) Clarify that authenticated state can be entered by the CLOSE
5735 command.
5736
5737 111) Emphasize that SELECT and EXAMINE are the exceptions to the rule
5738 that a failing command does not change state.
5739
5740 112) Clarify that newly-appended messages have the Recent flag set.
5741
5742 113) Clarify that newly-copied messages SHOULD have the Recent flag
5743 set.
5744
5745 114) Clarify that UID commands always return the UID in FETCH
5746 responses.
5747
5748 C. Key Word Index
5749
5750 +FLAGS <flag list> (store command data item) ............... 59
5751 +FLAGS.SILENT <flag list> (store command data item) ........ 59
5752 -FLAGS <flag list> (store command data item) ............... 59
5753 -FLAGS.SILENT <flag list> (store command data item) ........ 59
5754 ALERT (response code) ...................................... 64
5755 ALL (fetch item) ........................................... 55
5756 ALL (search key) ........................................... 50
5757 ANSWERED (search key) ...................................... 50
5758 APPEND (command) ........................................... 45
5759 AUTHENTICATE (command) ..................................... 27
5760 BAD (response) ............................................. 66
5761 BADCHARSET (response code) ................................. 64
5762 BCC <string> (search key) .................................. 51
5763 BEFORE <date> (search key) ................................. 51
5764 BODY (fetch item) .......................................... 55
5765 BODY (fetch result) ........................................ 73
5766 BODY <string> (search key) ................................. 51
5767
5768
5769
5770 Crispin Standards Track [Page 103]
5771
5772 RFC 3501 IMAPv4 March 2003
5773
5774
5775 BODY.PEEK[<section>]<<partial>> (fetch item) ............... 57
5776 BODYSTRUCTURE (fetch item) ................................. 57
5777 BODYSTRUCTURE (fetch result) ............................... 74
5778 BODY[<section>]<<origin octet>> (fetch result) ............. 74
5779 BODY[<section>]<<partial>> (fetch item) .................... 55
5780 BYE (response) ............................................. 67
5781 Body Structure (message attribute) ......................... 12
5782 CAPABILITY (command) ....................................... 24
5783 CAPABILITY (response code) ................................. 64
5784 CAPABILITY (response) ...................................... 68
5785 CC <string> (search key) ................................... 51
5786 CHECK (command) ............................................ 47
5787 CLOSE (command) ............................................ 48
5788 COPY (command) ............................................. 59
5789 CREATE (command) ........................................... 34
5790 DELETE (command) ........................................... 35
5791 DELETED (search key) ....................................... 51
5792 DRAFT (search key) ......................................... 51
5793 ENVELOPE (fetch item) ...................................... 57
5794 ENVELOPE (fetch result) .................................... 77
5795 EXAMINE (command) .......................................... 33
5796 EXISTS (response) .......................................... 71
5797 EXPUNGE (command) .......................................... 48
5798 EXPUNGE (response) ......................................... 72
5799 Envelope Structure (message attribute) ..................... 12
5800 FAST (fetch item) .......................................... 55
5801 FETCH (command) ............................................ 54
5802 FETCH (response) ........................................... 73
5803 FLAGGED (search key) ....................................... 51
5804 FLAGS (fetch item) ......................................... 57
5805 FLAGS (fetch result) ....................................... 78
5806 FLAGS (response) ........................................... 71
5807 FLAGS <flag list> (store command data item) ................ 59
5808 FLAGS.SILENT <flag list> (store command data item) ......... 59
5809 FROM <string> (search key) ................................. 51
5810 FULL (fetch item) .......................................... 55
5811 Flags (message attribute) .................................. 11
5812 HEADER (part specifier) .................................... 55
5813 HEADER <field-name> <string> (search key) .................. 51
5814 HEADER.FIELDS <header-list> (part specifier) ............... 55
5815 HEADER.FIELDS.NOT <header-list> (part specifier) ........... 55
5816 INTERNALDATE (fetch item) .................................. 57
5817 INTERNALDATE (fetch result) ................................ 78
5818 Internal Date (message attribute) .......................... 12
5819 KEYWORD <flag> (search key) ................................ 51
5820 Keyword (type of flag) ..................................... 11
5821 LARGER <n> (search key) .................................... 51
5822 LIST (command) ............................................. 40
5823
5824
5825
5826 Crispin Standards Track [Page 104]
5827
5828 RFC 3501 IMAPv4 March 2003
5829
5830
5831 LIST (response) ............................................ 69
5832 LOGIN (command) ............................................ 30
5833 LOGOUT (command) ........................................... 25
5834 LSUB (command) ............................................. 43
5835 LSUB (response) ............................................ 70
5836 MAY (specification requirement term) ....................... 4
5837 MESSAGES (status item) ..................................... 45
5838 MIME (part specifier) ...................................... 56
5839 MUST (specification requirement term) ...................... 4
5840 MUST NOT (specification requirement term) .................. 4
5841 Message Sequence Number (message attribute) ................ 10
5842 NEW (search key) ........................................... 51
5843 NO (response) .............................................. 66
5844 NOOP (command) ............................................. 25
5845 NOT <search-key> (search key) .............................. 52
5846 OK (response) .............................................. 65
5847 OLD (search key) ........................................... 52
5848 ON <date> (search key) ..................................... 52
5849 OPTIONAL (specification requirement term) .................. 4
5850 OR <search-key1> <search-key2> (search key) ................ 52
5851 PARSE (response code) ...................................... 64
5852 PERMANENTFLAGS (response code) ............................. 64
5853 PREAUTH (response) ......................................... 67
5854 Permanent Flag (class of flag) ............................. 12
5855 READ-ONLY (response code) .................................. 65
5856 READ-WRITE (response code) ................................. 65
5857 RECENT (response) .......................................... 72
5858 RECENT (search key) ........................................ 52
5859 RECENT (status item) ....................................... 45
5860 RENAME (command) ........................................... 37
5861 REQUIRED (specification requirement term) .................. 4
5862 RFC822 (fetch item) ........................................ 57
5863 RFC822 (fetch result) ...................................... 78
5864 RFC822.HEADER (fetch item) ................................. 57
5865 RFC822.HEADER (fetch result) ............................... 78
5866 RFC822.SIZE (fetch item) ................................... 57
5867 RFC822.SIZE (fetch result) ................................. 78
5868 RFC822.TEXT (fetch item) ................................... 58
5869 RFC822.TEXT (fetch result) ................................. 79
5870 SEARCH (command) ........................................... 49
5871 SEARCH (response) .......................................... 71
5872 SEEN (search key) .......................................... 52
5873 SELECT (command) ........................................... 31
5874 SENTBEFORE <date> (search key) ............................. 52
5875 SENTON <date> (search key) ................................. 52
5876 SENTSINCE <date> (search key) .............................. 52
5877 SHOULD (specification requirement term) .................... 4
5878 SHOULD NOT (specification requirement term) ................ 4
5879
5880
5881
5882 Crispin Standards Track [Page 105]
5883
5884 RFC 3501 IMAPv4 March 2003
5885
5886
5887 SINCE <date> (search key) .................................. 52
5888 SMALLER <n> (search key) ................................... 52
5889 STARTTLS (command) ......................................... 27
5890 STATUS (command) ........................................... 44
5891 STATUS (response) .......................................... 70
5892 STORE (command) ............................................ 58
5893 SUBJECT <string> (search key) .............................. 53
5894 SUBSCRIBE (command) ........................................ 38
5895 Session Flag (class of flag) ............................... 12
5896 System Flag (type of flag) ................................. 11
5897 TEXT (part specifier) ...................................... 56
5898 TEXT <string> (search key) ................................. 53
5899 TO <string> (search key) ................................... 53
5900 TRYCREATE (response code) .................................. 65
5901 UID (command) .............................................. 60
5902 UID (fetch item) ........................................... 58
5903 UID (fetch result) ......................................... 79
5904 UID <sequence set> (search key) ............................ 53
5905 UIDNEXT (response code) .................................... 65
5906 UIDNEXT (status item) ...................................... 45
5907 UIDVALIDITY (response code) ................................ 65
5908 UIDVALIDITY (status item) .................................. 45
5909 UNANSWERED (search key) .................................... 53
5910 UNDELETED (search key) ..................................... 53
5911 UNDRAFT (search key) ....................................... 53
5912 UNFLAGGED (search key) ..................................... 53
5913 UNKEYWORD <flag> (search key) .............................. 53
5914 UNSEEN (response code) ..................................... 65
5915 UNSEEN (search key) ........................................ 53
5916 UNSEEN (status item) ....................................... 45
5917 UNSUBSCRIBE (command) ...................................... 39
5918 Unique Identifier (UID) (message attribute) ................ 8
5919 X<atom> (command) .......................................... 62
5920 [RFC-2822] Size (message attribute) ........................ 12
5921 \Answered (system flag) .................................... 11
5922 \Deleted (system flag) ..................................... 11
5923 \Draft (system flag) ....................................... 11
5924 \Flagged (system flag) ..................................... 11
5925 \Marked (mailbox name attribute) ........................... 69
5926 \Noinferiors (mailbox name attribute) ...................... 69
5927 \Noselect (mailbox name attribute) ......................... 69
5928 \Recent (system flag) ...................................... 11
5929 \Seen (system flag) ........................................ 11
5930 \Unmarked (mailbox name attribute) ......................... 69
5931
5932
5933
5934
5935
5936
5937
5938 Crispin Standards Track [Page 106]
5939
5940 RFC 3501 IMAPv4 March 2003
5941
5942
5943 Author's Address
5944
5945 Mark R. Crispin
5946 Networks and Distributed Computing
5947 University of Washington
5948 4545 15th Avenue NE
5949 Seattle, WA 98105-4527
5950
5951 Phone: (206) 543-5762
5952
5953 EMail: MRC@CAC.Washington.EDU
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994 Crispin Standards Track [Page 107]
5995
5996 RFC 3501 IMAPv4 March 2003
5997
5998
5999 Full Copyright Statement
6000
6001 Copyright (C) The Internet Society (2003). All Rights Reserved.
6002
6003 This document and translations of it may be copied and furnished to
6004 others, and derivative works that comment on or otherwise explain it
6005 or assist in its implementation may be prepared, copied, published
6006 and distributed, in whole or in part, without restriction of any
6007 kind, provided that the above copyright notice and this paragraph are
6008 included on all such copies and derivative works. However, this
6009 document itself may not be modified in any way, such as by removing
6010 the copyright notice or references to the Internet Society or other
6011 Internet organizations, except as needed for the purpose of
6012 developing Internet standards in which case the procedures for
6013 copyrights defined in the Internet Standards process must be
6014 followed, or as required to translate it into languages other than
6015 English.
6016
6017 The limited permissions granted above are perpetual and will not be
6018 revoked by the Internet Society or its successors or assigns. v This
6019 document and the information contained herein is provided on an "AS
6020 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
6021 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
6022 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL
6023 NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY
6024 OR FITNESS FOR A PARTICULAR PURPOSE.
6025
6026 Acknowledgement
6027
6028 Funding for the RFC Editor function is currently provided by the
6029 Internet Society.
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050 Crispin Standards Track [Page 108]
6051