git.fiddlerwoaroof.com
Browse code

initial storage

jkf authored on 16/09/1999 21:47:26
Showing 7 changed files
imap.cl
History View file @ 5885760
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,1248 @@
1 
+;; imap protocol
2 
+;; (with hooks for pop too)
3 
+
4 
+(defpackage :mailbox
5 
+  (:nicknames :mb)
6 
+  (:use :lisp :excl)
7 
+  (:export
8 
+   #:address-name
9 
+   #:address-additional
10 
+   #:address-mailbox
11 
+   #:address-host
12 
+
13 
+   #:alter-flags
14 
+   #:close-imap-connection
15 
+   #:close-mailbox
16 
+   #:copy-to-mailbox
17 
+   #:create-mailbox
18 
+   #:delete-letter
19 
+   #:delete-mailbox
20 
+
21 
+   #:envelope-date
22 
+   #:envelope-subject
23 
+   #:envelope-from
24 
+   #:envelope-sender
25 
+   #:envelope-reply-to
26 
+   #:envelope-to
27 
+   #:envelope-cc
28 
+   #:envelope-bcc
29 
+   #:envelope-in-reply-to
30 
+   #:envelope-message-id
31 
+
32 
+   #:expunge-mailbox
33 
+   #:fetch-field
34 
+   #:fetch-letter
35 
+   #:mailbox-flags      ; accessor
36 
+   #:mailbox-permanent-flags ; acc
37 
+   #:mailbox-list
38 
+   #:mailbox-list-flags
39 
+   #:mailbox-list-separator
40 
+   #:mailbox-list-name
41 
+   #:mailbox-message-count ; accessor
42 
+   #:mailbox-recent-messages ; ac
43 
+   #:mailbox-separator  ; accessor
44 
+   #:mailbox-uidvalidity
45 
+   #:make-imap-connection
46 
+   #:noop
47 
+   #:rename-mailbox
48 
+   #:search-mailbox
49 
+   #:select-mailbox
50 
+   )
51 
+  )
52 
+
53 
+(in-package :mailbox)
54 
+
55 
+; kinds of things that come back from the server
56 
+; <tag> OK random text
57 
+; <tag> OK [atom] random text
58 
+; <tag> OK [atom value] random text
59 
+; * <number> atom random text
60 
+; * LIST (atom ...) string string
61 
+; * STATUS mboxname (atom value .... ...)
62 
+; * CAPABILITY atom ...
63 
+
64 
+; our parsing will return
65 
+; tag
66 
+;    a string or :untagged or :continue
67 
+; command
68 
+;    the string like "OK" which describes what this response is saying
69 
+; args
70 
+;    list of arguments.
71 
+;
72 
+
73 
+(defvar *debug-imap* nil)
74 
+
75 
+
76 
+(defclass mailbox ()
77 
+  ((socket :initarg :socket
78 
+	   :accessor mailbox-socket)
79 
+
80 
+   (host :initarg :host
81 
+	 :accessor  mailbox-host
82 
+	 :initform nil)
83 
+   (user  :initarg :user
84 
+	  :accessor mailbox-user
85 
+	  :initform nil)
86 
+
87 
+   (state :accessor mailbox-state
88 
+	  :initarg :state
89 
+	  :initform :unconnected)
90 
+
91 
+   (timeout
92 
+    ;; time to wait for network activity for actions that should
93 
+    ;; happen very quickly when things are operating normally
94 
+    :initarg :timeout
95 
+    :initform 60
96 
+    :accessor timeout)
97 
+  ))
98 
+
99 
+(defclass imap-mailbox (mailbox)
100 
+  ((mailbox-name   ; currently selected mailbox
101 
+    :accessor mailbox-name
102 
+    :initform nil)
103 
+
104 
+   (separator
105 
+    ;; string that separates mailbox names in the hierarchy
106 
+    :accessor mailbox-separator
107 
+    :initform "")
108 
+
109 
+   ;;; these slots hold information about the currently select mailbox:
110 
+
111 
+    (message-count  ; how many in the mailbox
112 
+    :accessor mailbox-message-count
113 
+    :initform 0)
114 
+
115 
+   (recent-messages ; how many messages since we last checked
116 
+    :accessor mailbox-recent-messages
117 
+    :initform 0)
118 
+
119 
+   (uidvalidity  ; used to denote messages uniquely
120 
+    :accessor mailbox-uidvalidity
121 
+    :initform 0)
122 
+
123 
+   (uidnext
124 
+    :accessor mailbox-uidnext ;; predicted next uid
125 
+    :initform 0)
126 
+
127 
+   (flags	; list of flags that can be stored in a message
128 
+    :accessor mailbox-flags
129 
+    :initform nil)
130 
+
131 
+   (permanent-flags  ; list of flags that be stored permanently
132 
+    :accessor mailbox-permanent-flags
133 
+    :initform nil)
134 
+
135 
+   (first-unseen   ; number of the first unseen message
136 
+    :accessor first-unseen
137 
+    :initform 0)
138 
+
139 
+   ;;; end list of values for the currently selected maibox
140 
+   )
141 
+  )
142 
+
143 
+
144 
+(defclass pop-mailbox (mailbox)
145 
+  ())
146 
+
147 
+
148 
+
149 
+(defstruct (mailbox-list (:type list))
150 
+  ;; a list of these are returned by mailbox-list
151 
+  flags
152 
+  separator
153 
+  name)
154 
+
155 
+
156 
+
157 
+(defstruct (envelope (:type list))
158 
+  ;; returned by fetch-letter as the value of the envelope property
159 
+  date
160 
+  subject
161 
+  from
162 
+  sender
163 
+  reply-to
164 
+  to
165 
+  cc
166 
+  bcc
167 
+  in-reply-to
168 
+  message-id)
169 
+
170 
+
171 
+(defstruct (address (:type list))
172 
+  name     ;; often the person's full name
173 
+  additional
174 
+  mailbox  ;; the login name
175 
+  host	   ;; the name of the machine
176 
+  )
177 
+
178 
+
179 
+(defparameter *imap-tags* '("t01" "t02" "t03" "t04" "t05" "t06" "t07"))
180 
+(defvar *cur-imap-tags* nil)
181 
+
182 
+(defvar *crlf*
183 
+    (let ((str (make-string 2)))
184 
+      (setf (aref str 0) #\return)
185 
+      (setf (aref str 1) #\linefeed)
186 
+      str))
187 
+
188 
+(defun make-imap-connection (host &key (port 143)
189 
+				       user
190 
+				       password
191 
+				       (timeout 30))
192 
+  (let* ((sock (socket:make-socket :remote-host host
193 
+				   :remote-port port))
194 
+	 (imap (make-instance 'imap-mailbox
195 
+		 :socket sock
196 
+		 :host   host
197 
+		 :timeout timeout
198 
+		 :state :unauthorized)))
199 
+
200 
+    (multiple-value-bind (tag)
201 
+	(get-and-parse-from-imap-server imap)
202 
+      (if* (not (eq :untagged tag))
203 
+	 then  (error "unexpected line from server after connect")))
204 
+
205 
+    ; now login
206 
+    (send-command-get-results imap
207 
+			      (format nil "login ~a ~a" user password)
208 
+			      #'handle-untagged-response
209 
+			      #'(lambda (mb command count extra)
210 
+				  (check-for-success mb command count extra
211 
+						     "login")))
212 
+
213 
+    ; find the separator character
214 
+    (let ((res (mailbox-list imap)))
215 
+      ;;
216 
+      (let ((sep (cadr  (car res))))
217 
+	(if* sep
218 
+	   then (setf (mailbox-separator imap) sep))))
219 
+
220 
+
221 
+
222 
+    imap))
223 
+
224 
+
225 
+(defmethod close-imap-connection ((mb imap-mailbox))
226 
+
227 
+  (let ((sock (mailbox-socket mb)))
228 
+    (if* sock
229 
+       then (ignore-errors
230 
+	     (send-command-get-results
231 
+	      mb
232 
+	      "logout"
233 
+	      ; don't want to get confused by untagged
234 
+	      ; bye command, which is expected here
235 
+	      #'(lambda (mb command count extra)
236 
+		  (declare (ignore mb command count extra))
237 
+		  nil)
238 
+	      #'(lambda (mb command count extra)
239 
+		  (check-for-success mb command count extra
240 
+				     "logout")))))
241 
+    (setf (mailbox-socket mb) nil)
242 
+    (if* sock then (ignore-errors (close sock)))
243 
+    t))
244 
+
245 
+
246 
+(defmethod send-command-get-results ((mb imap-mailbox)
247 
+				     command untagged-handler tagged-handler)
248 
+  ;; send a command and retrieve results until we get the tagged
249 
+  ;; response for the command we sent
250 
+  ;;
251 
+  (let ((tag (get-next-tag)))
252 
+    (format (mailbox-socket mb)
253 
+	    "~a ~a~a" tag command *crlf*)
254 
+    (force-output (mailbox-socket mb))
255 
+
256 
+    (if* *debug-imap*
257 
+       then (format t
258 
+		    "~a ~a~a" tag command *crlf*)
259 
+	    (force-output))
260 
+    (loop
261 
+      (multiple-value-bind (got-tag cmd count extra)
262 
+	  (get-and-parse-from-imap-server mb)
263 
+	(if* (eq got-tag :untagged)
264 
+	   then (funcall untagged-handler mb cmd count extra)
265 
+	 elseif (equal tag got-tag)
266 
+	   then (funcall tagged-handler mb cmd count extra)
267 
+		(return)
268 
+	   else (warn "received tag ~s out of order" got-tag))))))
269 
+
270 
+
271 
+(defun get-next-tag ()
272 
+  (let ((tag (pop *cur-imap-tags*)))
273 
+    (if*  tag
274 
+       thenret
275 
+       else (setq *cur-imap-tags* *imap-tags*)
276 
+	    (pop *cur-imap-tags*))))
277 
+
278 
+(defun handle-untagged-response (mb command count extra)
279 
+  ;; default function to handle untagged responses, which are
280 
+  ;; really just returning general state information about
281 
+  ;; the mailbox
282 
+  (case command
283 
+    (:exists (setf (mailbox-message-count mb) count))
284 
+    (:recent (setf (mailbox-recent-messages mb) count))
285 
+    (:flags  (setf (mailbox-flags mb) (mapcar #'kwd-intern extra)))
286 
+    (:bye ; occurs when connection times out or mailbox lock is stolen
287 
+     (ignore-errors (close (mailbox-socket mb)))
288 
+     (error "connection to the imap server was closed by the server"))
289 
+    (:no ; used when grabbing a lock from another process
290 
+     (warn "grabbing mailbox lock from another process"))
291 
+    (:ok ; a whole variety of things
292 
+     (if* extra
293 
+	then (if* (equalp (car extra) "unseen")
294 
+		then (setf (first-unseen mb) (cadr extra))
295 
+	      elseif (equalp (car extra) "uidvalidity")
296 
+		then (setf (mailbox-uidvalidity mb) (cadr extra))
297 
+	      elseif (equalp (car extra) "uidnext")
298 
+		then (setf (mailbox-uidnext mb) (cadr extra))
299 
+	      elseif (equalp (car extra) "permanentflags")
300 
+		then (setf (mailbox-permanent-flags mb)
301 
+		       (mapcar #'kwd-intern (cadr extra)))
302 
+		else (warn "unknown ok response ~s" extra))))
303 
+    (t (warn "unknown untagged response ~a ~a" command extra)))
304 
+
305 
+  )
306 
+
307 
+(defun convert-flags-plist (plist)
308 
+  ;; scan the plist looking for "flags" indicators and
309 
+  ;; turn value into a list of symbols rather than strings
310 
+  (do ((xx plist (cddr xx)))
311 
+      ((null xx) plist)
312 
+    (if* (equalp "flags" (car xx))
313 
+       then (setf (cadr xx) (mapcar #'kwd-intern (cadr xx))))))
314 
+
315 
+
316 
+(defun select-mailbox (mb name)
317 
+  ;; select the given maibox
318 
+  (send-command-get-results mb
319 
+			    (format nil "select ~a" name)
320 
+			    #'handle-untagged-response
321 
+			    #'(lambda (mb command count extra)
322 
+				(declare (ignore mb count extra))
323 
+				(if* (not (eq command :ok))
324 
+				   then (error "imap mailbox select failed"))))
325 
+  (setf (mailbox-name mb) name)
326 
+  t
327 
+  )
328 
+
329 
+
330 
+
331 
+(defun fetch-letter (mb number parts &key uid)
332 
+  (let (res)
333 
+    (send-command-get-results
334 
+     mb
335 
+     (format nil "~afetch ~a ~a"
336 
+	     (if* uid then "uid " else "")
337 
+	     (message-set-string number)
338 
+	     (or parts "body[]")
339 
+	     )
340 
+     #'(lambda (mb command count extra)
341 
+	 (if* (eq command :fetch)
342 
+	    then (push (list count (internalize-flags extra)) res)
343 
+	    else (handle-untagged-response
344 
+		  mb command count extra)))
345 
+     #'(lambda (mb command count extra)
346 
+	 (declare (ignore mb count extra))
347 
+	 (if* (not (eq command :ok))
348 
+	    then (error "imap mailbox fetch failed"))))
349 
+    res))
350 
+
351 
+
352 
+(defun fetch-field (letter-number field-name info &key uid)
353 
+  ;; given the information from a fetch-letter, return the
354 
+  ;; particular field for the particular letter
355 
+  ;;
356 
+  ;; info is as returned by fetch
357 
+  ;; field-name is a string, case doesn't matter.
358 
+  ;;
359 
+  (dolist (item info)
360 
+    ;; item is (messagenumber plist-info)
361 
+    ;; the same messagenumber may appear in multiple items
362 
+    (let (use-this)
363 
+      (if* uid
364 
+	 then ; uid appears as a property in the value, not
365 
+	      ; as the top level message sequence number
366 
+	      (do ((xx (cadr item) (cddr xx)))
367 
+		  ((null xx))
368 
+		(if* (equalp "uid" (car xx))
369 
+		   then (if* (eql letter-number (cadr xx))
370 
+			   then (return (setq use-this t))
371 
+			   else (return))))
372 
+	 else ; just a message sequence number
373 
+	      (setq use-this (eql letter-number (car item))))
374 
+
375 
+      (if* use-this
376 
+	 then (do ((xx (cadr item) (cddr xx)))
377 
+		  ((null xx))
378 
+		(if* (equalp field-name (car xx))
379 
+		   then (return-from fetch-field (cadr xx))))))))
380 
+
381 
+
382 
+
383 
+(defun internalize-flags (stuff)
384 
+  ;; given a plist like object, look for items labelled "flags" and
385 
+  ;; convert the contents to internal flags objects
386 
+  (do ((xx stuff (cddr xx)))
387 
+      ((null xx))
388 
+    (if* (equalp (car xx) "flags")
389 
+       then (setf (cadr xx) (mapcar #'kwd-intern (cadr xx)))
390 
+	    (return)))
391 
+
392 
+  stuff)
393 
+
394 
+
395 
+
396 
+
397 
+(defun delete-letter (mb messages &key (expunge t) uid)
398 
+  ;; delete all the mesasges and do the expunge to make
399 
+  ;; it permanent if expunge is true
400 
+  (alter-flags mb messages :add-flags :\\deleted :uid uid)
401 
+  (if* expunge then (expunge-mailbox mb)))
402 
+
403 
+
404 
+
405 
+(defun noop (mb)
406 
+  ;; just poke the server... keeping it awake and checking for
407 
+  ;; new letters
408 
+  (send-command-get-results mb
409 
+			    "noop"
410 
+			    #'handle-untagged-response
411 
+			    #'(lambda (mb command count extra)
412 
+				(check-for-success
413 
+				 mb command count extra
414 
+				 "noop"))))
415 
+
416 
+
417 
+(defun check-for-success (mb command count extra command-string)
418 
+  (declare (ignore mb count extra))
419 
+  (if* (not (eq command :ok))
420 
+     then (error "imap ~a failed" command-string)))
421 
+
422 
+
423 
+
424 
+
425 
+
426 
+(defun mailbox-list (mb &key (reference "") (pattern ""))
427 
+  ;; return a list of mailbox names with respect to a given
428 
+  (let (res)
429 
+    (send-command-get-results mb
430 
+			      (format nil "list ~s ~s" reference pattern)
431 
+			      #'(lambda (mb command count extra)
432 
+				  (if* (eq command :list)
433 
+				     then (push extra res)
434 
+				     else (handle-untagged-response
435 
+					   mb command count extra)))
436 
+			      #'(lambda (mb command count extra)
437 
+				  (check-for-success
438 
+				   mb command count extra "list")))
439 
+
440 
+    ;; the car of each list is a set of keywords, make that so
441 
+    (dolist (rr res)
442 
+      (setf (car rr) (mapcar #'kwd-intern (car rr))))
443 
+
444 
+    res
445 
+
446 
+
447 
+    ))
448 
+
449 
+
450 
+(defun create-mailbox (mb mailbox-name)
451 
+  ;; create a mailbox name of the given name.
452 
+  ;; use mailbox-separator if you want to create a hierarchy
453 
+  (send-command-get-results mb
454 
+			    (format nil "create ~s" mailbox-name)
455 
+			    #'handle-untagged-response
456 
+			    #'(lambda (mb command count extra)
457 
+				  (check-for-success
458 
+				   mb command count extra "create")))
459 
+  t)
460 
+
461 
+
462 
+(defun delete-mailbox (mb mailbox-name)
463 
+  ;; create a mailbox name of the given name.
464 
+  ;; use mailbox-separator if you want to create a hierarchy
465 
+  (send-command-get-results mb
466 
+			    (format nil "delete ~s" mailbox-name)
467 
+			    #'handle-untagged-response
468 
+			    #'(lambda (mb command count extra)
469 
+				  (check-for-success
470 
+				   mb command count extra "delete"))))
471 
+
472 
+(defun rename-mailbox (mb old-mailbox-name new-mailbox-name)
473 
+  ;; create a mailbox name of the given name.
474 
+  ;; use mailbox-separator if you want to create a hierarchy
475 
+  (send-command-get-results mb
476 
+			    (format nil "rename ~s ~s"
477 
+				    old-mailbox-name
478 
+				    new-mailbox-name)
479 
+			    #'handle-untagged-response
480 
+			    #'(lambda (mb command count extra)
481 
+				  (check-for-success
482 
+				   mb command count extra "rename"))))
483 
+
484 
+
485 
+
486 
+(defun alter-flags (mb messages &key (flags nil flags-p) add-flags remove-flags
487 
+				      silent uid)
488 
+  ;;
489 
+  ;; change the flags using the store command
490 
+  ;;
491 
+  (let (cmd val res)
492 
+    (if* flags-p
493 
+       then (setq cmd "flags" val flags)
494 
+     elseif add-flags
495 
+       then (setq cmd "+flags" val add-flags)
496 
+     elseif remove-flags
497 
+       then (setq cmd "-flags" val remove-flags)
498 
+       else (return-from alter-flags nil))
499 
+
500 
+    (if* (atom val) then (setq val (list val)))
501 
+
502 
+    (send-command-get-results mb
503 
+			      (format nil "~astore ~a ~a~a ~a"
504 
+				      (if* uid then "uid " else "")
505 
+				      (message-set-string messages)
506 
+				      cmd
507 
+				      (if* silent
508 
+					 then ".silent"
509 
+					 else "")
510 
+				      (if* val
511 
+					 thenret
512 
+					 else "()"))
513 
+			      #'(lambda (mb command count extra)
514 
+				  (if* (eq command :fetch)
515 
+				     then (push (list count
516 
+						      (convert-flags-plist
517 
+						       extra))
518 
+						res)
519 
+				     else (handle-untagged-response
520 
+					   mb command count extra)))
521 
+
522 
+			      #'(lambda (mb command count extra)
523 
+				  (check-for-success
524 
+				   mb command count extra "store")))
525 
+    res))
526 
+
527 
+
528 
+(defun message-set-string (messages)
529 
+  ;; return a string that describes the messages which may be a
530 
+  ;; single number or a sequence of numbers
531 
+
532 
+  (if* (atom messages)
533 
+     then (format nil "~a" messages)
534 
+     else (if* (and (consp messages)
535 
+		    (eq :seq (car messages)))
536 
+	     then (format nil "~a:~a" (cadr messages) (caddr messages))
537 
+	     else (let ((str (make-string-output-stream))
538 
+			(precomma nil))
539 
+		    (dolist (msg messages)
540 
+		      (if* precomma then (format str ","))
541 
+		      (if* (atom msg)
542 
+			 then (format str "~a" msg)
543 
+		       elseif (eq :seq (car msg))
544 
+			 then (format str
545 
+				      "~a:~a" (cadr msg) (caddr msg))
546 
+			 else (error "bad message list ~s" msg))
547 
+		      (setq precomma t))
548 
+		    (get-output-stream-string str)))))
549 
+
550 
+
551 
+
552 
+
553 
+
554 
+
555 
+(defmethod expunge-mailbox ((mb imap-mailbox))
556 
+  ;; remove messages marked as deleted
557 
+  (let (res)
558 
+    (send-command-get-results mb
559 
+			      "expunge"
560 
+			      #'(lambda (mb command count extra)
561 
+				  (if* (eq command :expunge)
562 
+				     then (push count res)
563 
+				     else (handle-untagged-response
564 
+					   mb command count extra)))
565 
+			      #'(lambda (mb command count extra)
566 
+				  (check-for-success
567 
+				   mb command count extra "expunge")))
568 
+    (nreverse res)))
569 
+
570 
+
571 
+
572 
+(defmethod close-mailbox ((mb imap-mailbox))
573 
+  ;; remove messages marked as deleted
574 
+  (send-command-get-results mb
575 
+			    "close"
576 
+			    #'handle-untagged-response
577 
+
578 
+			    #'(lambda (mb command count extra)
579 
+				(check-for-success
580 
+				 mb command count extra "close")))
581 
+  t)
582 
+
583 
+
584 
+
585 
+(defmethod copy-to-mailbox ((mb imap-mailbox) message-list destination
586 
+			    &key uid)
587 
+  (send-command-get-results mb
588 
+			    (format nil "~acopy ~a ~s"
589 
+				    (if* uid then "uid " else "")
590 
+				    (message-set-string message-list)
591 
+				    destination)
592 
+			    #'handle-untagged-response
593 
+			    #'(lambda (mb command count extra)
594 
+				(check-for-success
595 
+				 mb command count extra "copy")))
596 
+  t)
597 
+
598 
+
599 
+;; search command
600 
+
601 
+(defun search-mailbox (mb search-expression &key uid)
602 
+  (let (res)
603 
+    (send-command-get-results mb
604 
+			      (format nil "~asearch ~a"
605 
+				      (if* uid then "uid " else "")
606 
+				      (build-search-string search-expression))
607 
+			      #'(lambda (mb command count extra)
608 
+				  (if* (eq command :search)
609 
+				     then (setq res (append res extra))
610 
+				     else (handle-untagged-response
611 
+					   mb command count extra)))
612 
+			      #'(lambda (mb command count extra)
613 
+				  (check-for-success
614 
+				   mb command count extra "search")))
615 
+    res))
616 
+
617 
+
618 
+(defmacro defsearchop (name &rest operands)
619 
+  (if* (null operands)
620 
+     then `(setf (get ',name 'imap-search-no-args) t)
621 
+     else `(setf (get ',name 'imap-search-args) ',operands)))
622 
+
623 
+(defsearchop :all)
624 
+(defsearchop :answered)
625 
+(defsearchop :bcc :str)
626 
+(defsearchop :before :date)
627 
+(defsearchop :body :str)
628 
+(defsearchop :cc :str)
629 
+(defsearchop :deleted)
630 
+(defsearchop :draft)
631 
+(defsearchop :flagged)
632 
+(defsearchop :from :str)
633 
+(defsearchop :header :str :str)
634 
+(defsearchop :keyword :flag)
635 
+(defsearchop :larger :number)
636 
+(defsearchop :new)
637 
+(defsearchop :old)
638 
+(defsearchop :on :date)
639 
+(defsearchop :recent)
640 
+(defsearchop :seen)
641 
+(defsearchop :sentbefore :date)
642 
+(defsearchop :senton :date)
643 
+(defsearchop :sentsince :date)
644 
+(defsearchop :since :date)
645 
+(defsearchop :smaller :number)
646 
+(defsearchop :subject :str)
647 
+(defsearchop :text :str)
648 
+(defsearchop :to :str)
649 
+(defsearchop :uid :messageset)
650 
+(defsearchop :unanswered)
651 
+(defsearchop :undeleted)
652 
+(defsearchop :undraft)
653 
+(defsearchop :unflagged)
654 
+(defsearchop :unkeyword :flag)
655 
+(defsearchop :unseen)
656 
+
657 
+
658 
+
659 
+(defun build-search-string (search)
660 
+  ;; take the lisp search form and turn it into a string that can be
661 
+  ;; passed to imap
662 
+
663 
+  (if* (null search)
664 
+     then ""
665 
+     else (let ((str (make-string-output-stream)))
666 
+	    (bss-int search str)
667 
+	    (get-output-stream-string str))))
668 
+
669 
+(defun bss-int (search str)
670 
+  ;;* it turns out that imap (on linux) is very picky about spaces....
671 
+  ;; any extra whitespace will result in failed searches
672 
+  ;;
673 
+  (labels ((and-ify (srch str)
674 
+	     (let ((spaceout nil))
675 
+	       (dolist (xx srch)
676 
+		 (if* spaceout then (format str " "))
677 
+		 (bss-int xx str)
678 
+		 (setq spaceout t))))
679 
+	   (or-ify (srch str)
680 
+	     ; only binary or allowed in imap but we support n-ary
681 
+	     ; or in this interface
682 
+	     (if* (null (cdr srch))
683 
+		then (bss-int (car srch) str)
684 
+	      elseif (cddr srch)
685 
+		then ; over two clauses
686 
+		     (format str "or (")
687 
+		     (bss-int (car srch) str)
688 
+		     (format str  ") (")
689 
+		     (or-ify (cdr srch) str)
690 
+		     (format str ")")
691 
+		else ; 2 args
692 
+		     (format str "or (" )
693 
+		     (bss-int (car srch) str)
694 
+		     (format str ") (")
695 
+		     (bss-int (cadr srch) str)
696 
+		     (format str ")")))
697 
+	   (set-ify (srch str)
698 
+	     ;; a sequence of messages
699 
+	     (do* ((xsrch srch (cdr xsrch))
700 
+		   (val (car xsrch) (car xsrch)))
701 
+		 ((null xsrch))
702 
+	       (if* (integerp val)
703 
+		  then (format str "~s" val)
704 
+		elseif (and (consp val)
705 
+			    (eq :seq (car val))
706 
+			    (eq 3 (length val)))
707 
+		  then (format str "~s:~s" (cadr val) (caddr val))
708 
+		  else (error "illegal set format ~s" val))
709 
+	       (if* (cdr xsrch) then (format str ","))))
710 
+	   (arg-process (str args arginfo)
711 
+	     ;; process and print each arg to str
712 
+	     ;; assert (length of args and arginfo are the same)
713 
+	     (do* ((x-args args (cdr x-args))
714 
+		   (val (car x-args) (car x-args))
715 
+		   (x-arginfo arginfo (cdr x-arginfo)))
716 
+		 ((null x-args))
717 
+	       (ecase (car x-arginfo)
718 
+		 (:str
719 
+		  ; print it as a string
720 
+		  (format str " \"~a\"" (car x-args)))
721 
+		 (:date
722 
+
723 
+		  (if* (integerp val)
724 
+		     then (setq val (universal-time-to-rfc822-date
725 
+				     val))
726 
+		   elseif (not (stringp val))
727 
+		     then (error "illegal value for date search ~s"
728 
+				 val))
729 
+		  ;; val is now a string
730 
+		  (format str " ~s" val))
731 
+		 (:number
732 
+
733 
+		  (if* (not (integerp val))
734 
+		     then (error "illegal value for number in search ~s" val))
735 
+		  (format str " ~s" val))
736 
+		 (:flag
737 
+
738 
+		  ;; should be a symbol in the kwd package
739 
+		  (setq val (string val))
740 
+		  (format str " ~s" val))
741 
+		 (:messageset
742 
+		  (if* (numberp val)
743 
+		     then (format str " ~s" val)
744 
+		   elseif (consp val)
745 
+		     then (set-ify val str)
746 
+		     else (error "illegal message set ~s" val)))
747 
+
748 
+		 ))))
749 
+
750 
+    (if* (symbolp search)
751 
+       then (if* (get search 'imap-search-no-args)
752 
+	       then (format str "~a"  (string-upcase
753 
+					(string search)))
754 
+	       else (error "illegal search word: ~s" search))
755 
+     elseif (consp search)
756 
+       then (case (car search)
757 
+	      (and (if* (null (cdr search))
758 
+		      then (bss-int :all str)
759 
+		    elseif (null (cddr search))
760 
+		      then (bss-int (cadr search) str)
761 
+		      else (and-ify (cdr search)  str)))
762 
+	      (or  (if* (null (cdr search))
763 
+		      then (bss-int :all str)
764 
+		    elseif (null (cddr search))
765 
+		      then (bss-int (cadr search) str)
766 
+		      else (or-ify (cdr search)  str)))
767 
+	      (not (if* (not (eql (length search) 2))
768 
+		      then (error "not takes one argument: ~s" search))
769 
+		   (format str "not (" )
770 
+		   (bss-int (cadr search) str)
771 
+		   (format str ")"))
772 
+	      (:seq
773 
+	       (set-ify (list search) str))
774 
+	      (t (let (arginfo)
775 
+		   (if* (and (symbolp (car search))
776 
+			     (setq arginfo (get (car search)
777 
+						'imap-search-args)))
778 
+		      then
779 
+			   (format str "~a" (string-upcase
780 
+					       (string (car search))))
781 
+			   (if* (not (equal (length (cdr search))
782 
+					    (length arginfo)))
783 
+			      then (error "wrong number of arguments to ~s" search))
784 
+
785 
+			   (arg-process str (cdr search) arginfo)
786 
+
787 
+		    elseif (integerp (car search))
788 
+		      then (set-ify search str)
789 
+		      else (error "Illegal form ~s in search string" search)))))
790 
+     elseif (integerp search)
791 
+       then ;  a message number
792 
+	    (format str "~s" search)
793 
+       else (error "Illegal form ~s in search string" search))))
794 
+
795 
+
796 
+
797 
+
798 
+
799 
+
800 
+
801 
+
802 
+
803 
+
804 
+(defmethod get-and-parse-from-imap-server ((mb imap-mailbox))
805 
+  ;; read the next line and parse it.... see parse-imap-response
806 
+  ;; for the return value of this function.
807 
+  ;;
808 
+  (multiple-value-bind (line count)
809 
+      (get-line-from-server mb)
810 
+    (if* *debug-imap*
811 
+       then (format t "from server: " count)
812 
+	    (dotimes (i count)(write-char (schar line i)))
813 
+	    (terpri))
814 
+
815 
+    (parse-imap-response line count)
816 
+    ))
817 
+
818 
+
819 
+;; Parse and return the data from each line
820 
+;; values returned
821 
+;;  tag -- either a string or the symbol :untagged
822 
+;;  command -- a keyword symbol naming the command, like :ok
823 
+;;  count -- a number which preceeded the command, or nil if
824 
+;;	     there wasn't a command
825 
+;;  bracketted - a list of objects found in []'s after the command
826 
+;;            or in ()'s after the command  or sometimes just
827 
+;;	      out in the open after the command (like the search)
828 
+;;
829 
+(defun parse-imap-response (line end)
830 
+  (let (kind value next
831 
+	tag count command extra-data)
832 
+
833 
+    ;; get tag
834 
+    (multiple-value-setq (kind value next)
835 
+      (get-next-token line 0 end))
836 
+
837 
+    (case kind
838 
+      (:string (setq tag (if* (equal value "*")
839 
+			    then :untagged
840 
+			    else value)))
841 
+      (t (error "Illegal tag on response: ~s" (subseq line 0 count))))
842 
+
843 
+    ;; get command
844 
+    (multiple-value-setq (kind value next)
845 
+      (get-next-token line next end))
846 
+
847 
+    (tagbody again
848 
+      (case kind
849 
+	(:number (setq count value)
850 
+		 (multiple-value-setq (kind value next)
851 
+		   (get-next-token line next end))
852 
+		 (go again))
853 
+	(:string (setq command (kwd-intern value)))
854 
+	(t (error "Illegal command on response: ~s" (subseq line 0 count)))))
855 
+
856 
+    ;; now the part after the command... this gets tricky
857 
+    (loop
858 
+      (multiple-value-setq (kind value next)
859 
+	(get-next-token line next end))
860 
+
861 
+      (case kind
862 
+	((:lbracket :lparen)
863 
+	 (multiple-value-setq (kind value next)
864 
+	   (get-next-sexpr line (1- next) end))
865 
+	 (case kind
866 
+	   (:sexpr (push value extra-data))
867 
+	   (t (error "bad sexpr form"))))
868 
+	(:eof (return nil))
869 
+	((:number :string :nil) (push value extra-data))
870 
+	(t  ; should never happen
871 
+	 (return)))
872 
+
873 
+      (if* (not (member command '(:list :search) :test #'eq))
874 
+	 then ; only one item returned
875 
+	      (setq extra-data (car extra-data))
876 
+	      (return)))
877 
+
878 
+    (if* (member command '(:list :search) :test #'eq)
879 
+       then (setq extra-data (nreverse extra-data)))
880 
+
881 
+
882 
+    (values tag command count extra-data)))
883 
+
884 
+
885 
+
886 
+(defun get-next-sexpr (line start end)
887 
+  ;; read a whole s-expression
888 
+  ;; return 3 values
889 
+  ;;   kind -- :sexpr  or :rparen or :rbracket
890 
+  ;;   value - the sexpr value
891 
+  ;;   next  - next charpos to scan
892 
+  ;;
893 
+  (let ( kind value next)
894 
+    (multiple-value-setq (kind value next) (get-next-token line start end))
895 
+
896 
+    (case kind
897 
+      ((:string :number :nil)
898 
+        (values :sexpr value next))
899 
+      (:eof (error "eof inside sexpr"))
900 
+      ((:lbracket :lparen)
901 
+       (let (res)
902 
+	 (loop
903 
+	   (multiple-value-setq (kind value next)
904 
+	     (get-next-sexpr line next end))
905 
+	   (case kind
906 
+	     (:sexpr (push value res))
907 
+	     ((:rparen :rbracket)
908 
+	      (return (values :sexpr (nreverse res) next)))
909 
+	     (t (error "bad sexpression"))))))
910 
+      ((:rbracket :rparen)
911 
+       (values kind nil next))
912 
+      (t (error "bad sexpression")))))
913 
+
914 
+
915 
+
916 
+
917 
+(defparameter *char-to-kind*
918 
+    (let ((arr (make-array 256 :initial-element nil)))
919 
+
920 
+      (do ((i #.(char-code #\0) (1+ i)))
921 
+	  ((> i #.(char-code #\9)))
922 
+	(setf (aref arr i) :number))
923 
+
924 
+      (setf (aref arr #.(char-code #\space)) :space)
925 
+      (setf (aref arr #.(char-code #\tab)) :space)
926 
+
927 
+      (setf (aref arr #.(char-code #\[)) :lbracket)
928 
+      (setf (aref arr #.(char-code #\])) :rbracket)
929 
+      (setf (aref arr #.(char-code #\()) :lparen)
930 
+      (setf (aref arr #.(char-code #\))) :rparen)
931 
+      (setf (aref arr #.(char-code #\")) :dquote)
932 
+
933 
+      (setf (aref arr #.(char-code #\^b)) :big-string) ; our own invention
934 
+
935 
+      arr))
936 
+
937 
+
938 
+(defun get-next-token (line start end)
939 
+  ;; scan past whitespace for the next token
940 
+  ;; return three values:
941 
+  ;;  kind:  :string , :number, :eof, :lbracket, :rbracket,
942 
+  ;;		:lparen, :rparen
943 
+  ;;  value:  the value, either a string or number or nil
944 
+  ;;  next:   the character pos to start scanning for the next token
945 
+  ;;
946 
+  (let (ch chkind colstart (count 0) (state :looking)
947 
+	collector right-bracket-is-normal)
948 
+    (loop
949 
+      ; pick up the next character
950 
+      (if* (>= start end)
951 
+	 then (if* (eq state :looking)
952 
+		 then (return (values :eof nil start))
953 
+		 else (setq ch #\space))
954 
+	 else (setq ch (schar line start)))
955 
+
956 
+      (setq chkind (aref *char-to-kind* (char-code ch)))
957 
+
958 
+      (case state
959 
+	(:looking
960 
+	 (case chkind
961 
+	   (:space nil)
962 
+	   (:number (setq state :number)
963 
+		    (setq colstart start)
964 
+		    (setq count (- (char-code ch) #.(char-code #\0))))
965 
+	   ((:lbracket :lparen :rbracket :rparen)
966 
+	    (return (values chkind nil (1+ start))))
967 
+	   (:dquote
968 
+	    (setq collector (make-array 10
969 
+					:element-type 'character
970 
+					:adjustable t
971 
+					:fill-pointer 0))
972 
+	    (setq state :qstring))
973 
+	   (:big-string
974 
+	    (setq colstart (1+ start))
975 
+	    (setq state :big-string))
976 
+	   (t (setq colstart start)
977 
+	      (setq state :literal))))
978 
+	(:number
979 
+	 (case chkind
980 
+	   ((:space :lbracket :lparen :rbracket :rparen
981 
+	     :dquote) ; end of number
982 
+	    (return (values :number count  start)))
983 
+	   (:number ; more number
984 
+	    (setq count (+ (* count 10)
985 
+			   (- (char-code ch) #.(char-code #\0)))))
986 
+	   (t ; turn into an literal
987 
+	    (setq state :literal))))
988 
+	(:literal
989 
+	 (case chkind
990 
+	   ((:space :rbracket :lparen :rparen :dquote) ; end of literal
991 
+	    (if* (and (eq chkind :rbracket)
992 
+		      right-bracket-is-normal)
993 
+	       then nil ; don't stop now
994 
+	       else (let ((seq (subseq line colstart start)))
995 
+		      (if* (equal "NIL" seq)
996 
+			 then (return (values :nil
997 
+					      nil
998 
+					      start))
999 
+			 else (return (values :string
1000 
+					      seq
1001 
+					      start))))))
1002 
+	   (t (if* (eq chkind :lbracket)
1003 
+		 then ; imbedded left bracket so right bracket isn't
1004 
+		      ; a break char
1005 
+		      (setq right-bracket-is-normal t))
1006 
+	      nil)))
1007 
+	(:qstring
1008 
+	 ;; quoted string
1009 
+	 ; (format t "start is ~s  kind is ~s~%" start chkind)
1010 
+	 (case chkind
1011 
+	   (:dquote
1012 
+	    ;; end of string
1013 
+	    (return (values :string collector (1+ start))))
1014 
+	   (t (if* (eq ch #\\)
1015 
+		 then ; escaping the next character
1016 
+		      (incf start)
1017 
+		      (if* (>= start end)
1018 
+			 then (error "eof in string returned"))
1019 
+		      (setq ch (schar line start)))
1020 
+	      (vector-push-extend ch collector)
1021 
+
1022 
+	      (if* (>= start end)
1023 
+		 then ; we overran the end of the input
1024 
+		      (error "eof in string returned")))))
1025 
+	(:big-string
1026 
+	 ;; super string... just a block of data
1027 
+	 ; (format t "start is ~s  kind is ~s~%" start chkind)
1028 
+	 (case chkind
1029 
+	   (:big-string
1030 
+	    ;; end of string
1031 
+	    (return (values :string
1032 
+			    (subseq line colstart start)
1033 
+			    (1+ start))))
1034 
+	   (t nil)))
1035 
+
1036 
+
1037 
+	)
1038 
+
1039 
+      (incf start))))
1040 
+
1041 
+
1042 
+
1043 
+
1044 
+
1045 
+(defun kwd-intern (string)
1046 
+  ;; convert the string to the current preferred case
1047 
+  ;; and then intern
1048 
+  (intern (case excl::*current-case-mode*
1049 
+	    ((:case-sensitive-lower
1050 
+	      :case-insensitive-lower) (string-downcase string))
1051 
+	    (t (string-upcase string)))
1052 
+	  *keyword-package*))
1053 
+
1054 
+
1055 
+
1056 
+
1057 
+
1058 
+
1059 
+
1060 
+
1061 
+
1062 
+
1063 
+
1064 
+
1065 
+
1066 
+
1067 
+;; low level i/o to server
1068 
+
1069 
+(defun get-line-from-server (mailbox)
1070 
+  ;; Return two values:  a buffer and a character count.
1071 
+  ;; The character count includes up to but excluding the cr lf that
1072 
+  ;;  was read from the socket.
1073 
+  ;;
1074 
+  (let* ((buff (get-line-buffer 0))
1075 
+	 (len  (length buff))
1076 
+	 (i 0)
1077 
+	 (p (mailbox-socket mailbox))
1078 
+	 (ch nil)
1079 
+	 (whole-count)
1080 
+	 )
1081 
+
1082 
+    (flet ((grow-buffer (size)
1083 
+	     (let ((newbuff (get-line-buffer size)))
1084 
+	       (dotimes (j i)
1085 
+		 (setf (schar newbuff j) (schar buff j)))
1086 
+	       (free-line-buffer buff)
1087 
+	       (setq buff newbuff)
1088 
+	       (setq len (length buff)))))
1089 
+
1090 
+      ;; increase the buffer to at least size
1091 
+      ;; this is somewhat complex to ensure that we aren't doing
1092 
+      ;; buffer allocation within the with-timeout form, since
1093 
+      ;; that could trigger a gc which could then cause the
1094 
+      ;; with-timeout form to expire.
1095 
+      (loop
1096 
+
1097 
+	(if* whole-count
1098 
+	   then ; we should now read in this may bytes and
1099 
+		; append it to this buffer
1100 
+		(multiple-value-bind (ans this-count)
1101 
+		    (get-block-of-data-from-server mailbox whole-count)
1102 
+		  ; now put this data in the current buffer
1103 
+		  (if* (> (+ i whole-count 5) len)
1104 
+		     then  ; grow the initial buffer
1105 
+			  (grow-buffer (+ i whole-count 100)))
1106 
+
1107 
+		  (dotimes (ind this-count)
1108 
+		    (setf (schar buff i) (schar ans ind))
1109 
+		    (incf i))
1110 
+		  (setf (schar buff i) #\^b) ; end of inset string
1111 
+		  (incf i)
1112 
+		  (free-line-buffer ans)
1113 
+		  )
1114 
+	 elseif ch
1115 
+	   then ; we're growing the buffer holding the line data
1116 
+		(grow-buffer (+ len 200))
1117 
+		(setf (schar buff i) ch)
1118 
+		(incf i))
1119 
+
1120 
+	(block timeout
1121 
+	  (mp:with-timeout ((timeout mailbox)
1122 
+			    (error "imap server failed to respond"))
1123 
+	    ;; read up to lf  (lf most likely preceeded by cr)
1124 
+	    (loop
1125 
+	      (setq ch (read-char p))
1126 
+	      (if* (eq #\linefeed ch)
1127 
+		 then ; end of line. Don't save the return
1128 
+		      (if* (and (> i 0)
1129 
+				(eq (schar buff (1- i)) #\return))
1130 
+			 then ; remove #\return, replace with newline
1131 
+			      (decf i)
1132 
+			      (setf (schar buff i) #\newline)
1133 
+			      )
1134 
+		      ;; must check for an extended return value which
1135 
+		      ;; is indicated by a {nnn} at the end of the line
1136 
+		      (block count-check
1137 
+			(let ((ind (1- i)))
1138 
+			  (if* (and (>= i 0) (eq (schar buff ind) #\}))
1139 
+			     then (let ((count 0)
1140 
+					(mult 1))
1141 
+				    (loop
1142 
+				      (decf ind)
1143 
+				      (if* (< ind 0)
1144 
+					 then ; no of the form {nnn}
1145 
+					      (return-from count-check))
1146 
+				      (setf ch (schar buff ind))
1147 
+				      (if* (eq ch #\{)
1148 
+					 then ; must now read that many bytes
1149 
+					      (setf (schar buff ind) #\^b)
1150 
+					      (setq whole-count count)
1151 
+					      (setq i (1+ ind))
1152 
+					      (return-from timeout)
1153 
+				       elseif (<= #.(char-code #\0)
1154 
+						 (char-code ch)
1155 
+						 #.(char-code #\9))
1156 
+					 then ; is a digit
1157 
+					      (setq count
1158 
+						(+ count
1159 
+						   (* mult
1160 
+						      (- (char-code ch)
1161 
+							 #.(char-code #\0)))))
1162 
+					      (setq mult (* 10 mult))
1163 
+					 else ; invalid form, get out
1164 
+					      (return-from count-check)))))))
1165 
+
1166 
+
1167 
+		      (return-from get-line-from-server
1168 
+			(values buff i))
1169 
+		 else ; save character
1170 
+		      (if* (>= i len)
1171 
+			 then ; need bigger buffer
1172 
+			      (return))
1173 
+		      (setf (schar buff i) ch)
1174 
+		      (incf i)))))))))
1175 
+
1176 
+
1177 
+(defun get-block-of-data-from-server  (mb count &key save-returns)
1178 
+  ;; read count bytes from the server returning it in a line buffer object
1179 
+  ;; return as a second value the number of characters saved
1180 
+  ;; (we drop #\return's so that lines are sepisarated by a #\newline
1181 
+  ;; like lisp likes).
1182 
+  ;;
1183 
+  (let ((buff (get-line-buffer count))
1184 
+	(p (mailbox-socket mb))
1185 
+	(ind 0))
1186 
+    (mp:with-timeout ((timeout mb)
1187 
+		      (error "imap server timed out"))
1188 
+
1189 
+      (dotimes (i count)
1190 
+	(if* (eq #\return (setf (schar buff ind) (read-char p)))
1191 
+	   then (if* save-returns then (incf ind)) ; drop #\returns
1192 
+	   else (incf ind)))
1193 
+
1194 
+
1195 
+      (values buff ind))))
1196 
+
1197 
+
1198 
+;;-- reusable line buffers
1199 
+
1200 
+(defvar *line-buffers* nil)
1201 
+
1202 
+(defun get-line-buffer (size)
1203 
+  ;; get a buffer of at least size bytes
1204 
+  (mp::without-scheduling
1205 
+    (dolist (buff *line-buffers* (make-string size))
1206 
+	(if* (>= (length buff) size)
1207 
+	   then ; use this one
1208 
+		(setq *line-buffers* (delete buff *line-buffers*))
1209 
+		(return buff)))))
1210 
+
1211 
+
1212 
+(defun free-line-buffer (buff)
1213 
+  (mp:without-scheduling
1214 
+    (push buff *line-buffers*)))
1215 
+
1216 
+
1217 
+;;;;;;;
1218 
+
1219 
+; date functions
1220 
+
1221 
+(defun universal-time-to-rfc822-date (ut)
1222 
+  ;; convert a lisp universal time to rfc 822 date
1223 
+  ;;
1224 
+  (multiple-value-bind
1225 
+      (sec min hour date month year day-of-week dsp time-zone)
1226 
+      (decode-universal-time ut 0)
1227 
+    (declare (ignore time-zone sec min hour day-of-week dsp time-zone))
1228 
+    (format nil "~d-~a-~d"
1229 
+	    date
1230 
+	    (svref
1231 
+	     '#(nil "Jan" "Feb" "Mar" "Apr" "May" "Jun"
1232 
+		"Jul" "Aug" "Sep" "Oct" "Nov" "Dec")
1233 
+	     month
1234 
+	     )
1235 
+	    year)))
1236 
+
1237 
+
1238 
+
1239 
+
1240 
+
1241 
+
1242 
+
1243 
+
1244 
+
1245 
+
1246 
+
1247 
+
1248 
+
imap.html
History View file @ 5885760
0 1249 
new file mode 100644
... ... 
@@ -0,0 +1,800 @@
1 
+<html>
2 
+
3 
+<head>
4 
+<title>Allegro CL imap interface</title>
5 
+<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
6 
+</head>
7 
+
8 
+<body>
9 
+
10 
+<h1 align="center">Allegro CL imap interface</h1>
11 
+
12 
+<p align="left">copyright (c) 1999 Franz Inc.</p>
13 
+
14 
+<p align="left">&nbsp;</p>
15 
+
16 
+<p align="left"><strong>imap</strong> is a client-server protocol for processing
17 
+electronic mail boxes.&nbsp; <strong>imap </strong>is the successor to the <strong>pop</strong>
18 
+protocol.&nbsp;&nbsp; It is not an upward compatible successor.</p>
19 
+
20 
+<p align="left">This document and interface is based on the Imap4rev1 protocol described
21 
+in rfc2060.&nbsp;&nbsp; Where this document is describing the actions of the imap commands
22 
+it should be considered a secondary source of information about those command and rfc2060
23 
+should be considered the primary source.</p>
24 
+
25 
+<p align="left">The advantages of <strong>imap</strong> over <strong>pop</strong> are:</p>
26 
+
27 
+<ol>
28 
+  <li><p align="left"><strong>imap </strong>can work with multiple mailboxes (<strong>pop </strong>works
29 
+    with a single mailbox)</p>
30 
+  </li>
31 
+  <li><p align="left">With <strong>imap</strong> you're encouraged to leave mail in mailboxes
32 
+    on the server machine, thus it can be read from any machine on the network. &nbsp;&nbsp;
33 
+    With <strong>pop</strong> you're encouraged to download the mail to the client machine's
34 
+    disk, and it thus becomes inaccessible to all other client machines.</p>
35 
+  </li>
36 
+  <li><p align="left"><strong>imap</strong> parses the headers of messages thus allowing
37 
+    easier analysis of mail messages by the client program.</p>
38 
+  </li>
39 
+  <li><p align="left"><strong>imap</strong> supports searching messages for data and sorting
40 
+    by date.</p>
41 
+  </li>
42 
+  <li><p align="left"><strong>imap </strong>supports annotating messages with flags, thus
43 
+    making subsequent searching easier.</p>
44 
+  </li>
45 
+</ol>
46 
+
47 
+<p align="left">&nbsp;</p>
48 
+
49 
+<h1 align="left">Mailboxes</h1>
50 
+
51 
+<p align="left">Mailboxes are repositories for messages.&nbsp;&nbsp; Mailboxes are named
52 
+by Lisp strings.&nbsp; The mailbox &quot;inbox&quot; always exists and it is the mailbox
53 
+in which new messages are stored.&nbsp;&nbsp; New mailboxes can be created.
54 
+&nbsp;&nbsp;&nbsp; They can have simple names, like &quot;foo&quot; or they can have
55 
+hierarchical names (like &quot;clients/california/widgetco&quot;).&nbsp;&nbsp; After
56 
+connecting to an imap server you can determine what string of characters you must use
57 
+between simple names to create a hierarchical name (in this example &quot;/&quot; was the
58 
+separator character). </p>
59 
+
60 
+<p align="left">Each mailbox has an associated unique number called its <strong>uidvalidity</strong>.
61 
+&nbsp;&nbsp;&nbsp; This number won't change as long as only <strong>imap</strong> is the
62 
+only program used to manipulate the mailbox.&nbsp;&nbsp; In fact if you see that the
63 
+number has changed then that means that some other program has done something to the
64 
+mailbox that destroyed the information that <strong>imap</strong> had been keeping about
65 
+the mailbox.&nbsp;&nbsp;&nbsp; In particular you can't now retrieve messages by their
66 
+unique ids that you had used before.</p>
67 
+
68 
+<h1 align="left">Messages</h1>
69 
+
70 
+<p align="left">Messages in a mailbox can be denoted in one of two ways:&nbsp; message
71 
+sequence number or&nbsp; unique id.&nbsp;&nbsp; </p>
72 
+
73 
+<p align="left">The <em>message sequence number</em> is the normal way.&nbsp; The messages
74 
+in a mailbox are numbered from 1 to N where N is the number of messages in the mailbox.
75 
+&nbsp;&nbsp; There are never any gaps in the sequence numbers.&nbsp; If you tell <strong>imap</strong>
76 
+to delete messages 3,4 and 5 then it will return a value telling you the it has deleted
77 
+messages 3,3 and 3.&nbsp; This is because when you deleted message 3, message 4 became the
78 
+new message 3 just before it was deleted and then message 5 became message 3 just before
79 
+it was deleted.</p>
80 
+
81 
+<p align="left">A <em>unique id </em>of a message is a number associated with a message
82 
+that is unique only within a mailbox.&nbsp;&nbsp; As long as the uidvalidity value of a
83 
+mailbox doesn't change, the unique ids used in deleted messages will never be reused for
84 
+new messages.&nbsp; </p>
85 
+
86 
+<h1 align="left">Flags</h1>
87 
+
88 
+<p align="left">A flag is a symbol denoting that a message or mailbox has a certain
89 
+property.&nbsp;&nbsp; We use keywords in Lisp to denote flags.&nbsp;&nbsp; There are two
90 
+kinds of flags - System and User flags.&nbsp; System flags begin with the backslash
91 
+character, which is an unfortunate design decision&nbsp; since that means that in Lisp we
92 
+have to remember to use two backslashes (e.g.&nbsp; <strong>:\\deleted</strong>).
93 
+&nbsp;&nbsp; A subset of the flags can be stored permanently in the mailbox with the
94 
+messages.&nbsp; When a connection is made to an <strong>imap</strong> server it will
95 
+return the list of flags and permanent flags (and these are stored in the mailbox object
96 
+returned for access by the program).&nbsp;&nbsp; If the list of permanent flags includes <strong>:\\*</strong>
97 
+then the program can create its own flag names (not beginning with a backslash) and can
98 
+store them permanently in messages.</p>
99 
+
100 
+<p align="left">Some of the important system flags are:</p>
101 
+
102 
+<ul>
103 
+  <li><p align="left"><strong>:\\seen</strong> - this means that the message has been read
104 
+    &nbsp; (a <strong>fetch-letter</strong> has been done that includes the content of the
105 
+    message, not just its headers)</p>
106 
+  </li>
107 
+  <li><p align="left"><strong>:\\deleted </strong>- the message will be deleted the next time
108 
+    an <strong>expunge-mailbox</strong> or <strong>close-mailbox</strong> is done.</p>
109 
+  </li>
110 
+  <li><p align="left"><strong>:\\recent </strong>- this is the first session to have been
111 
+    notified about this message being present in the mailbox.</p>
112 
+  </li>
113 
+</ul>
114 
+
115 
+<p align="left">&nbsp;</p>
116 
+
117 
+<h1 align="left">Connecting to the server</h1>
118 
+
119 
+<p align="left">&nbsp;</p>
120 
+
121 
+<p align="left"><font face="Courier New">(<strong>make-imap-connection host &amp;key user
122 
+password port timeout)</strong></font></p>
123 
+
124 
+<p align="left">This creates a connection to the <strong>imap</strong> server on machine <strong>host</strong>
125 
+and logs in as <strong>user </strong>with password <strong>password.&nbsp;&nbsp; </strong>The
126 
+<strong>port</strong> argument defaults to143, which is the port on which the <strong>imap</strong>
127 
+server normally listens.&nbsp;&nbsp;&nbsp; The <strong>timeout</strong> argument defaults
128 
+to 30 (seconds) and this value is used to limit the amount of time this imap interface
129 
+code will wait for a response from the server before giving up.&nbsp;&nbsp;&nbsp; In
130 
+certain circumstances the server may get so busy that you see timeout errors signaled in
131 
+this code.&nbsp; In that case you should specify a larger timeout when connecting. </p>
132 
+
133 
+<p align="left">The <strong>make-imap-connection</strong> function returns a <strong>mailbox</strong>
134 
+object which is then passed to other functions in this interface.&nbsp;&nbsp; From this
135 
+one connection you can access all of the mailboxes owned by <strong>user</strong>.</p>
136 
+
137 
+<p align="left">After&nbsp; the connection is&nbsp; established a mailbox is <strong>not</strong>
138 
+selected.&nbsp;&nbsp; In this state attempting to execute message access functions may
139 
+result in cryptic error messages from the <strong>imap</strong> server that won't tell you
140 
+what you need to know -- that a mailbox is not selected.&nbsp;&nbsp; Therefore be sure to
141 
+select a mailbox using <strong>select-mailbox</strong> shortly after connecting.</p>
142 
+
143 
+<p align="left">&nbsp;</p>
144 
+
145 
+<p align="left">&nbsp;</p>
146 
+
147 
+<p align="left"><strong><font face="Courier New">(close-imap-connection mailbox)</font></strong></p>
148 
+
149 
+<p align="left">This sends a <strong>logout</strong> command to the <strong>imap</strong>
150 
+server and then closes the socket that's communicating with the <strong>imap</strong>
151 
+server.&nbsp;&nbsp;&nbsp; <strong>mailbox </strong>is the object returned by <strong>make-imap-connection.</strong>
152 
+&nbsp;&nbsp; This does <em>not</em> close the currently select mailbox before logging out,
153 
+thus messages marked to be deleted in the currently selected mailbox will <em>not</em> be
154 
+removed from the&nbsp; mailbox.&nbsp; Use <strong>close-mailbox</strong> or <strong>expunge-mailbox</strong>
155 
+before calling this <strong>close-imap-connection</strong> to ensure that messages to be
156 
+deleted are deleted.</p>
157 
+
158 
+<p align="left">&nbsp;</p>
159 
+
160 
+<p align="left">&nbsp;</p>
161 
+
162 
+<h1 align="left">Mailbox manipulation</h1>
163 
+
164 
+<p align="left">These functions work on mailboxes as a whole.&nbsp;&nbsp;&nbsp; The <strong>mailbox</strong>
165 
+argument to the functions is is the object returned by <strong>make-imap-connection.
166 
+&nbsp; </strong>If a return value isn't specified for a function then the return value
167 
+isn't important - if something goes wrong an error will be signaled.</p>
168 
+
169 
+<p align="left">&nbsp;</p>
170 
+
171 
+<p align="left"><font face="Courier New"><strong>(select-mailbox mailbox name)</strong></font></p>
172 
+
173 
+<p align="left">makes the mailbox named by the string <strong>name</strong> be the current
174 
+mailbox and store statistics about that mailbox in the <strong>mailbox</strong> object
175 
+where they can be retrieved by the accessors described below.&nbsp;&nbsp;&nbsp;&nbsp; The
176 
+selected mailbox is the source for all message manipulation functions.</p>
177 
+
178 
+<p align="left">&nbsp;</p>
179 
+
180 
+<p align="left"><font face="Courier New"><strong>(create-mailbox mailbox name)</strong></font></p>
181 
+
182 
+<p align="left">creates a new mailbox with the given <strong>name</strong>.&nbsp;&nbsp; It
183 
+is an error if the mailbox already exists.&nbsp; If you want to create a mailbox in a
184 
+hierarchy then you should be sure that it uses the correct hierarchy separator character
185 
+string (see <strong>mailbox-separator)</strong>.&nbsp;&nbsp; You do <strong>not</strong>
186 
+&nbsp; have to create intermediate levels of the hierarchy yourself -- just provide the
187 
+complete name and the <strong>imap</strong> server will create all necessary levels.</p>
188 
+
189 
+<p align="left">&nbsp;</p>
190 
+
191 
+<p align="left"><font face="Courier New"><strong>(delete-mailbox mailbox name)</strong></font></p>
192 
+
193 
+<p align="left">deletes the mailbox with the given name.</p>
194 
+
195 
+<p align="left">&nbsp;</p>
196 
+
197 
+<p align="left"><font face="Courier New"><strong>(rename-mailbox mailbox&nbsp; old-name
198 
+new-name)</strong></font></p>
199 
+
200 
+<p align="left">changes the name of mailbox <strong>old-name</strong> to <strong>new-name</strong>.
201 
+&nbsp; It's an error if <strong>new-name</strong> already exists.&nbsp; There's a special
202 
+behavior if <strong>old-name</strong> is &quot;inbox&quot;.&nbsp; In this case all of the
203 
+messages in &quot;inbox&quot; are moved to <strong>new-name </strong>mailbox, but the
204 
+&quot;inbox&quot; mailbox continues to exist.&nbsp;&nbsp; Note: The <strong>imap </strong>server
205 
+supplied with Linux does <strong>not</strong> support this special behavior of renaming
206 
+&quot;inbox&quot;.</p>
207 
+
208 
+<p align="left">&nbsp;</p>
209 
+
210 
+<p align="left"><strong><font face="Courier New">(mailbox-list mailbox &amp;key reference
211 
+pattern)</font></strong></p>
212 
+
213 
+<p align="left">returns a list of items describing the mailboxes that match the arguments.
214 
+&nbsp;&nbsp;&nbsp;&nbsp; The <strong>reference</strong> is the root of the hierarchy to
215 
+scan.&nbsp; By default is is the empty string (from which all mailboxes are reachable).
216 
+&nbsp;&nbsp;&nbsp; The <strong>pattern </strong>is a string matched against all mailbox
217 
+names reachable from <strong>reference. </strong>There are two special characters allowed
218 
+in the <strong>pattern:&nbsp; </strong>Asterisk (*) matches all characters including
219 
+hierarchy delimiters.&nbsp;&nbsp; Percent (%) matches all characters but not the hierarchy
220 
+delimiter.&nbsp; Thus</p>
221 
+
222 
+<p align="center"><font face="Courier New">(mailbox-list mailbox :pattern &quot;*&quot;)</font></p>
223 
+
224 
+<p align="left">returns a list of all mailboxes at all depths in the hierarchy.
225 
+&nbsp;&nbsp; </p>
226 
+
227 
+<p align="left">The value returned is a list of lists, but we've created the <strong>mailbox-list
228 
+</strong>struct definition in order to make accessing the parts of the inner lists &nbsp;
229 
+easier.&nbsp;&nbsp; The accessors for that structure are:</p>
230 
+
231 
+<p align="left">&nbsp;</p>
232 
+
233 
+<p align="left"><font face="Courier New"><strong>(mailbox-list-flags mailbox-list)&nbsp; </strong></font></p>
234 
+
235 
+<p align="left">returns the flags describing this entry.&nbsp;&nbsp; The most important
236 
+flag to check is <strong>:\\noselect</strong> as this specifies that this is not a mailbox
237 
+but instead just a directory in the hierarchy of mailboxes.&nbsp;&nbsp; The flag <strong>:\\noinferiors</strong>
238 
+specifies that you can't create a hierarchical mailbox name with this as a prefix.
239 
+&nbsp;&nbsp; This flag is often associated with the special mailbox &quot;inbox&quot;.</p>
240 
+
241 
+<p align="left">&nbsp;</p>
242 
+
243 
+<p align="left"><font face="Courier New"><strong>(mailbox-list-separator mailbox-list)</strong></font></p>
244 
+
245 
+<p align="left">returns a string containing the characters used to separate names in a
246 
+hierarchical name.</p>
247 
+
248 
+<p align="left">&nbsp;</p>
249 
+
250 
+<p align="left"><font face="Courier New"><strong>(mailbox-list-name mailbox-list)</strong></font></p>
251 
+
252 
+<p align="left">returns the name of the mailbox or directory (see mailbox-list-flags to
253 
+determine which it is).</p>
254 
+
255 
+<p align="left">&nbsp;</p>
256 
+
257 
+<h1 align="left">Message manipulation</h1>
258 
+
259 
+<p align="left">These functions work with the messages in the currently selected mailbox.
260 
+&nbsp;&nbsp;&nbsp; The <strong>mailbox</strong> argument is the object returned by <strong>make-imap-connection.</strong>
261 
+&nbsp; The <strong>messages</strong> argument is either a number (denoting a single
262 
+message), or is the list <strong>(:seq N M) </strong>denoting messages <strong>N</strong>
263 
+through <strong>M, </strong>or is a list of numbers and <strong>:seq </strong>forms
264 
+denoting the messages specified in the list.</p>
265 
+
266 
+<p align="left">&nbsp;</p>
267 
+
268 
+<p align="left">(<font face="Courier New"><strong>alter-flags mailbox messages &amp;key
269 
+flags add-flags remove-flags silent uid)</strong></font></p>
270 
+
271 
+<p>changes the flags of the messages in the specified way.&nbsp; Exactly one of&nbsp; <strong>flags,
272 
+add-flags</strong>, and <strong>remove-flags</strong> must&nbsp; be specified.&nbsp; <strong>flags</strong>
273 
+specifies the complete set of flags to be stores in the <strong>messages</strong> and the
274 
+other two add or remove flags.&nbsp;&nbsp; If <strong>uid</strong> is true then <strong>messages</strong>
275 
+will be interpreted as unique ids rather than message sequence numbers.
276 
+&nbsp;&nbsp;&nbsp;&nbsp; Normally <strong>alter-flags</strong> returns a data structure
277 
+that describes the state of the flags after the alternation has been done.&nbsp; This data
278 
+structure can be examined&nbsp; with the <strong>fetch-field</strong> function.
279 
+&nbsp;&nbsp; If <strong>silent</strong> is true then this data structure won't be created
280 
+thus saving some time and space.</p>
281 
+
282 
+<p>Removing a message from a mailbox is done by adding the <strong>:\\deleted</strong>
283 
+flag to the message and then either calling <strong>close-mailbox </strong>or <strong>expunge-mailbox.</strong></p>
284 
+
285 
+<p>&nbsp;</p>
286 
+
287 
+<p><font face="Courier New"><strong>(close-mailbox mailbox)</strong></font></p>
288 
+
289 
+<p>permanently removes all messages flagged as <strong>:\\deleted</strong> from the
290 
+currently selected mailbox and then un-selects the currently selected mailbox.&nbsp; After
291 
+this command has finished there is no currently selected mailbox.</p>
292 
+
293 
+<p align="left">&nbsp;</p>
294 
+
295 
+<p align="left"><font face="Courier New"><strong>(delete-letter mailbox messages &amp;key
296 
+expunge uid</strong></font>)</p>
297 
+
298 
+<p align="left">Mark the <strong>messages</strong> for deletion and then remove them
299 
+permanently (using <strong>expunge-mailbox</strong>) if <strong>expunge</strong> is true.
300 
+&nbsp;&nbsp; <strong>expunge </strong>defaults to true.&nbsp;&nbsp;&nbsp; If <strong>uid</strong>
301 
+is true then the message numbers are unique ids instead of messages sequence numbers.</p>
302 
+
303 
+<p align="left">&nbsp;</p>
304 
+
305 
+<p align="left"><font face="Courier New"><strong>(expunge-mailbox mailbox)</strong></font></p>
306 
+
307 
+<p align="left">permanently removes all messages flagged as <strong>:\\deleted</strong>
308 
+from the currently selected mailbox.&nbsp;&nbsp; The currently selected mailbox stays
309 
+selected.</p>
310 
+
311 
+<p align="left">&nbsp;</p>
312 
+
313 
+<p align="left"><font face="Courier New"><strong>(fetch-field message part info &amp;key
314 
+uid)</strong></font></p>
315 
+
316 
+<p align="left">is used to extract the desired information from the value returned by <strong>fetch-letter</strong>.
317 
+&nbsp;&nbsp;&nbsp; With <strong>fetch-letter</strong> you can retrieve a variety of
318 
+information about one or more messages and <strong>fetch-field</strong> can search though
319 
+that information and return a&nbsp; particular piece of information about a particular
320 
+letter.&nbsp;&nbsp; <strong>message</strong> is the message number (it's assumed to be a
321 
+message sequence number unless <strong>uid </strong>is true, in which case it's a unique
322 
+id).&nbsp;&nbsp; <strong>part </strong>is the type of information desired.&nbsp; It is a
323 
+string just as used in the call to <strong>fetch-letter</strong>.</p>
324 
+
325 
+<p align="left">&nbsp;</p>
326 
+
327 
+<p align="left"><font face="Courier New"><strong>(fetch-letter mailbox messages parts
328 
+&amp;key uid)</strong></font></p>
329 
+
330 
+<p align="left">retrieves the specified <strong>parts</strong> of the specified <strong>messages.
331 
+&nbsp;&nbsp; </strong>If <strong>uid</strong> is true then the <strong>messages</strong>
332 
+are considered to be unique ids rather than message sequence numbers.
333 
+&nbsp;&nbsp;&nbsp;&nbsp; The description of what can be specified for <strong>parts </strong>is
334 
+quite complex and has been moved to the section below &quot;Fetching a Letter&quot;.</p>
335 
+
336 
+<p align="left">The return value from this function is a structure that can be examined
337 
+with <strong>fetch-field</strong>.</p>
338 
+
339 
+<p align="left">When the result returned includes an envelope value the following
340 
+functions can be used to extract&nbsp; the parts of the envelope:</p>
341 
+
342 
+<ul>
343 
+  <li><p align="left"><font face="Courier New"><strong>envelope-date</strong></font></p>
344 
+  </li>
345 
+  <li><p align="left"><font face="Courier New"><strong>envelope-subject</strong></font></p>
346 
+  </li>
347 
+  <li><p align="left"><font face="Courier New"><strong>envelope-from</strong></font></p>
348 
+  </li>
349 
+  <li><p align="left"><font face="Courier New"><strong>envelope-sender</strong></font></p>
350 
+  </li>
351 
+  <li><p align="left"><font face="Courier New"><strong>envelope-reply-to</strong></font></p>
352 
+  </li>
353 
+  <li><p align="left"><font face="Courier New"><strong>envelope-to</strong></font></p>
354 
+  </li>
355 
+  <li><p align="left"><font face="Courier New"><strong>envelope-cc</strong></font></p>
356 
+  </li>
357 
+  <li><p align="left"><font face="Courier New"><strong>envelope-bcc</strong></font></p>
358 
+  </li>
359 
+  <li><p align="left"><font face="Courier New"><strong>envelope-in-reply-to</strong></font></p>
360 
+  </li>
361 
+  <li><p align="left"><font face="Courier New"><strong>envelope-message-id</strong></font></p>
362 
+  </li>
363 
+</ul>
364 
+
365 
+<p align="left">&nbsp;</p>
366 
+
367 
+<p align="left">&nbsp;</p>
368 
+
369 
+<p align="left"><strong><font face="Courier New">(noop mailbox)</font></strong></p>
370 
+
371 
+<p align="left">does nothing but&nbsp; remind the <strong>imap</strong> server that this
372 
+client is still active, thus resetting the timers used in the server that will
373 
+automatically shut down this connection after a period of inactivity.&nbsp;&nbsp; Like all
374 
+other commands if messages have been added to the currently selected mailbox, the server
375 
+will return the new message count as a response to the <strong>noop</strong> command, and
376 
+this can be check using <strong>mailbox-message-count</strong>.&nbsp;&nbsp;&nbsp; </p>
377 
+
378 
+<p align="left">&nbsp;</p>
379 
+
380 
+<p align="left"><font face="Courier New"><strong>(search-mailbox search-expression
381 
+&amp;key uid)</strong></font></p>
382 
+
383 
+<p align="left">return a list of messages in the mailbox that satisfy the<strong>
384 
+search-expression.&nbsp;&nbsp; </strong>If <strong>uid</strong> is true then unique ids
385 
+will be returned instead of message sequence numbers.&nbsp; See the section
386 
+&quot;Searching for messages&quot; for details on the <strong>search-expression</strong>.</p>
387 
+
388 
+<p align="left">&nbsp;</p>
389 
+
390 
+<h1 align="left">Mailbox Accessors</h1>
391 
+
392 
+<p align="left">The mailbox object contains information about the <strong>imap </strong>server
393 
+it's connected to as well as the currently selected mailbox.&nbsp;&nbsp; This information
394 
+can potentially be updated each time a request is made to the <strong>imap </strong>server.
395 
+&nbsp;&nbsp; The following functions access values from the mailbox object. </p>
396 
+
397 
+<p align="left"><font face="Courier New"><strong>(mailbox-flags mailbox)</strong></font></p>
398 
+
399 
+<p align="left">returns a complete list of flags used in all the messages in this mailbox.</p>
400 
+
401 
+<p align="left">&nbsp;</p>
402 
+
403 
+<p align="left"><font face="Courier New"><strong>(mailbox-permanent-flags mailbox)</strong></font></p>
404 
+
405 
+<p align="left">returns a list of flags that can be stored permanently in a message.
406 
+&nbsp; If the flag <strong>:\\*</strong> is present then it means that the client can
407 
+create its own flags.</p>
408 
+
409 
+<p align="left">&nbsp;</p>
410 
+
411 
+<p align="left"><font face="Courier New"><strong>(mailbox-message-count mailbox)</strong></font></p>
412 
+
413 
+<p align="left">returns the number of messages in the currently selected mailbox</p>
414 
+
415 
+<p align="left">&nbsp;</p>
416 
+
417 
+<p align="left"><font face="Courier New"><strong>(mailbox-recent-messages mailbox)</strong></font></p>
418 
+
419 
+<p align="left">returns the number of messages have just arrived in the mailbox.</p>
420 
+
421 
+<p align="left">&nbsp;</p>
422 
+
423 
+<p align="left"><font face="Courier New"><strong>(mailbox-separator mailbox)</strong></font></p>
424 
+
425 
+<p align="left">returns the hierarchy separator string for this <strong>imap </strong>server.</p>
426 
+
427 
+<p align="left">&nbsp;</p>
428 
+
429 
+<p align="left"><font face="Courier New"><strong>(mailbox-uidnext mailbox)</strong></font></p>
430 
+
431 
+<p align="left">returns the value predicated to be the&nbsp; unique id assigned to the
432 
+next message.</p>
433 
+
434 
+<p align="left">&nbsp;</p>
435 
+
436 
+<p align="left"><font face="Courier New"><strong>(mailbox-uidvalidty mailbox)</strong></font></p>
437 
+
438 
+<p align="left">returns the uidvalidity value for the currently selected mailbox.</p>
439 
+
440 
+<p align="left">&nbsp;</p>
441 
+
442 
+<p align="left">&nbsp;</p>
443 
+
444 
+<h1 align="left">Fetching a Letter</h1>
445 
+
446 
+<p align="left">When using <strong>fetch-letter</strong> to access letters, you must
447 
+specify the parts of the messages in which you're interested.&nbsp;&nbsp; There are a wide
448 
+variety of specifiers, some redundant and overlapping, described in the imap specification
449 
+in rfe2060.&nbsp; We'll describe the most common ones here.&nbsp;&nbsp; The specification
450 
+is always a string but it may be specify more than one thing by the use of parentheses in
451 
+the string, e.g. &quot;(flags envelope)&quot;.&nbsp;&nbsp; </p>
452 
+
453 
+<p align="left">The most common specifiers are:</p>
454 
+
455 
+<ul>
456 
+  <li><p align="left"><strong>body[]</strong> - this returns the full message: headers and
457 
+    body.</p>
458 
+  </li>
459 
+  <li><p align="left"><strong>body[text]</strong> - this returns just the the text of the body
460 
+    of the message, not the header.</p>
461 
+  </li>
462 
+  <li><p align="left"><strong>body</strong> - this returns a list describing the structure of
463 
+    the message.</p>
464 
+  </li>
465 
+  <li><p align="left"><strong>envelope</strong> - this parses the header and returns a list of
466 
+    information in it.&nbsp;&nbsp; We've defined a set of accessors <strong>(</strong>like<strong>
467 
+    envelope-xxx</strong>) that allow you to retrieve the envelope information easily.</p>
468 
+  </li>
469 
+  <li><p align="left"><strong>flags</strong> - return a list of the flags in the message</p>
470 
+  </li>
471 
+  <li><p align="left"><strong>uid</strong> - the unique identifier of the message</p>
472 
+  </li>
473 
+</ul>
474 
+
475 
+<p align="left">&nbsp;</p>
476 
+
477 
+<p align="left">The result of a <strong>fetch-letter</strong> is a data structure
478 
+containing all of the requested information.&nbsp;&nbsp; The <strong>fetch-field</strong>
479 
+function is then used to extract the particular information for the particular message.</p>
480 
+
481 
+<p align="left">&nbsp;</p>
482 
+
483 
+<h1 align="left">Searching for Messages</h1>
484 
+
485 
+<p align="left">.The <strong>imap</strong> server is able to search for messages matching
486 
+a search expression.&nbsp;&nbsp;&nbsp;&nbsp; A search-expression is a predicate or one of
487 
+these forms:</p>
488 
+
489 
+<ul>
490 
+  <li><p align="left">(<strong>and</strong> search-expression ...)</p>
491 
+  </li>
492 
+  <li><p align="left">(<strong>or</strong>&nbsp; search-expression ...)</p>
493 
+  </li>
494 
+  <li><p align="left">(<strong>not</strong> search-expression)</p>
495 
+  </li>
496 
+</ul>
497 
+
498 
+<p align="left">A predicate is </p>
499 
+
500 
+<ul>
501 
+  <li><p align="left">a number in which case the predicate is true if and only if we're are
502 
+    considering this message</p>
503 
+  </li>
504 
+  <li><p align="left">a <strong>(:seq N M)</strong> expression that is true if we're
505 
+    considering messages N through M.</p>
506 
+  </li>
507 
+  <li><p align="left"><strong>:all</strong> - this predicate is always true</p>
508 
+  </li>
509 
+  <li><p align="left"><strong>:answered</strong> - true if the message has the <strong>:\\answered</strong>
510 
+    flag</p>
511 
+  </li>
512 
+  <li><p align="left"><strong>(:bcc &quot;string&quot;) </strong>- true if the envelope
513 
+    structure's bcc field contains this &quot;string&quot;.</p>
514 
+  </li>
515 
+  <li><p align="left"><strong>(:before date)</strong> - true if the messages internal date is
516 
+    before this date.&nbsp; The date can either be a string in the rfc822 form (e.g.
517 
+    &quot;7-Mar-1999&quot;) or a lisp universal time.</p>
518 
+  </li>
519 
+  <li><p align="left"><strong>(:body &quot;string&quot;) </strong>- true if the body of the
520 
+    message contains &quot;string&quot;</p>
521 
+  </li>
522 
+  <li><p align="left"><strong>(:cc &quot;string&quot;)</strong> -&nbsp; true if the envelope
523 
+    structure's cc field contains this &quot;string&quot;.</p>
524 
+  </li>
525 
+  <li><p align="left"><strong>:deleted</strong> - true if the <strong>:\\deleted</strong> flag
526 
+    is set for this message</p>
527 
+  </li>
528 
+  <li><p align="left"><strong>:draft</strong> - true if the <strong>:\\draft </strong>flag is
529 
+    set for this message</p>
530 
+  </li>
531 
+  <li><p align="left"><strong>:flagged </strong>- true if the <strong>:\\flagged</strong> flag
532 
+    is set for this message</p>
533 
+  </li>
534 
+  <li><p align="left"><strong>(:from &quot;string&quot;)</strong> -&nbsp; true if the envelope
535 
+    structure's from&nbsp; field contains this &quot;string&quot;.</p>
536 
+  </li>
537 
+  <li><p align="left"><strong>(:header &quot;field&quot; &quot;string&quot;)</strong> - true
538 
+    if the message contains a header named &quot;field&quot; and its value contains
539 
+    &quot;string&quot;.</p>
540 
+  </li>
541 
+  <li><p align="left"><strong>(:keyword flag)</strong> - true if the specified flag is set for
542 
+    this message</p>
543 
+  </li>
544 
+  <li><p align="left"><strong>(:larger N)</strong> - true if the rfc822 size of the message is
545 
+    larger than N.</p>
546 
+  </li>
547 
+  <li><p align="left"><strong>:new </strong>- true if the message has the <strong>:\\recent</strong>
548 
+    flag set but not the <strong>:\\seen </strong>flag.</p>
549 
+  </li>
550 
+  <li><p align="left"><strong>:seen </strong>- true if the message has the <strong>:\\seen </strong>flag
551 
+    set.</p>
552 
+  </li>
553 
+  <li><p align="left"><strong>(:sentbefore date)</strong> - true if the message's Date header
554 
+    is earlier than the given date.&nbsp; See the description of :before for the format of
555 
+    dates.</p>
556 
+  </li>
557 
+  <li><p align="left"><strong>(:senton date)</strong> - true if the message's Date header is
558 
+    within the specified date.</p>
559 
+  </li>
560 
+  <li><p align="left"><strong>(:sentsince date) </strong>- true if the message's Date header
561 
+    is within or since the given date.</p>
562 
+  </li>
563 
+  <li><p align="left"><strong>(:smaller N)</strong> - true if the rfc822 size of the message
564 
+    is smaller than N</p>
565 
+  </li>
566 
+  <li><p align="left"><strong>(:subject &quot;string&quot;) </strong>- true if the Subject
567 
+    header line of the message contains &quot;string&quot;</p>
568 
+  </li>
569 
+  <li><p align="left"><strong>(:text &quot;string&quot;) </strong>- true if the message's
570 
+    header or body contains the specified &quot;string&quot;</p>
571 
+  </li>
572 
+  <li><p align="left"><strong>(:to &quot;string&quot;)</strong> - true if the envelope
573 
+    structure's to field contains this &quot;string&quot;.</p>
574 
+  </li>
575 
+  <li><p align="left"><strong>(:uid message-set)</strong> - true if the message is one of the
576 
+    message denoted by the message set, where the message set describes messages by unique id.</p>
577 
+  </li>
578 
+  <li><p align="left"><strong>:unanswered</strong> - true if the message does not have the <strong>:\\answered</strong>
579 
+    flag set</p>
580 
+  </li>
581 
+  <li><p align="left"><strong>:undeleted</strong> - true if the message does not have the <strong>:\\deleted</strong>
582 
+    flag set</p>
583 
+  </li>
584 
+  <li><p align="left"><strong>:undraft </strong>- true if the message does not have the <strong>:\\draft
585 
+    </strong>flag set.</p>
586 
+  </li>
587 
+  <li><p align="left"><strong>:unflagged </strong>- true if the message does not have the <strong>:\\flagged</strong>
588 
+    flag set.</p>
589 
+  </li>
590 
+  <li><p align="left"><strong>(:unkeyword flag)</strong> - true if the message does not have
591 
+    the specified flag set.</p>
592 
+  </li>
593 
+  <li><p align="left"><strong>:unseen </strong>- true if the message does not have the <strong>:\\seen
594 
+    </strong>flag set.</p>
595 
+  </li>
596 
+</ul>
597 
+
598 
+<p align="left">&nbsp;</p>
599 
+
600 
+<h1 align="left">Examples</h1>
601 
+
602 
+<p align="left">We show an example of using this interface</p>
603 
+
604 
+<p align="left">&nbsp;</p>
605 
+
606 
+<p align="left"><strong>Connect to the imap server on the machine holding the email:</strong></p>
607 
+<div align="left">
608 
+
609 
+<pre>user(2): (setq mb (mb:make-imap-connection &quot;mailmachine.franz.com&quot;
610 
+                            :user &quot;myacct&quot;
611 
+                            :password &quot;mypasswd&quot;))
612 
+#&lt;mailbox::imap-mailbox @ #x2064ca4a&gt;</pre>
613 
+</div>
614 
+
615 
+<p align="left">&nbsp;</p>
616 
+
617 
+<p align="left"><strong>Select the inbox, that's where the incoming mail arrives:</strong></p>
618 
+<div align="left">
619 
+
620 
+<pre>
621 
+user(3): (mb:select-mailbox mb &quot;inbox&quot;)
622 
+t</pre>
623 
+</div>
624 
+
625 
+<p align="left">&nbsp;</p>
626 
+
627 
+<p align="left"><strong>Check how many messages are in the mailbox:</strong></p>
628 
+<div align="left">
629 
+
630 
+<pre>
631 
+user(4): (mb:mailbox-message-count mb)
632 
+7</pre>
633 
+</div>
634 
+
635 
+<p align="left"><strong>There are seven messages at the moment.&nbsp;&nbsp; Fetch the
636 
+whole 4th message</strong></p>
637 
+<div align="left">
638 
+
639 
+<pre>
640 
+user(5): (setq body (mb:fetch-letter mb 4 &quot;body[]&quot;))
641 
+((4
642 
+(&quot;BODY[]&quot; &quot;Return-Path: &lt;jkfmail@tiger.franz.com&gt;
643 
+Received: from tiger.franz.com (jkf@tiger [192.132.95.103])
644 
+    by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261
645 
+    for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 11:36:26 -0700
646 
+Date: Mon, 13 Sep 1999 11:36:26 -0700
647 
+From: jkf mail tester &lt;jkfmail@tiger.franz.com&gt;
648 
+Message-Id: &lt;199909131836.LAA20261@tiger.franz.com&gt;
649 
+
650 
+message number 5
651 
+&quot;)))</pre>
652 
+</div>
653 
+
654 
+<p align="left"><strong>The value was returned inside a data structure designed to hold
655 
+information about one or more messages.&nbsp;&nbsp; In order to extract the particular
656 
+information we want we use fetch-field:</strong></p>
657 
+<div align="left">
658 
+
659 
+<pre>
660 
+user(6): (mb:fetch-field 4 &quot;body[]&quot; body)
661 
+&quot;Return-Path: &lt;jkfmail@tiger.franz.com&gt;
662 
+Received: from tiger.franz.com (jkf@tiger [192.132.95.103])
663 
+&nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with SMTP id LAA20261
664 
+&nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 11:36:26 -0700
665 
+Date: Mon, 13 Sep 1999 11:36:26 -0700
666 
+From: jkf mail tester &lt;jkfmail@tiger.franz.com&gt;
667 
+Message-Id: &lt;199909131836.LAA20261@tiger.franz.com&gt;
668 
+
669 
+message number 5
670 
+&quot;</pre>
671 
+</div>
672 
+
673 
+<p align="left"><strong>We use the search function to find all the messages containing the
674 
+word blitzfig.&nbsp; It turns out there is only one.&nbsp; We then extract the contents of
675 
+that message.</strong></p>
676 
+<div align="left">
677 
+
678 
+<pre>
679 
+user(7): (mb:search-mailbox mb '(:text &quot;blitzfig&quot;))
680 
+(7)
681 
+user(8): (mb:fetch-field 7 &quot;body[]&quot; (mb:fetch-letter mb 7 &quot;body[]&quot;))
682 
+&quot;Return-Path: &lt;jkf@verada.com&gt;
683 
+Received: from main.verada.com (main.verada.com [208.164.216.3])
684 
+&nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
685 
+&nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:37:24 -0700
686 
+Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
687 
+&nbsp;&nbsp;&nbsp; by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
688 
+&nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:36:54 -0700
689 
+Message-Id: &lt;199909132036.NAA06121@main.verada.com&gt;
690 
+To: jkfmail@tiger.franz.com
691 
+Subject: s test
692 
+Date: Mon, 13 Sep 1999 13:36:54 -0700
693 
+From: jkf &lt;jkf@verada.com&gt;
694 
+
695 
+secret word: blitzfig
696 
+ok?
697 
+&quot;</pre>
698 
+</div>
699 
+
700 
+<p align="left"><strong>We've been using message sequence numbers up to now.
701 
+&nbsp;&nbsp; The are the simplest to use but if you're concerned with keeping track of
702 
+messages when deletions are being done then using unique id's is useful.&nbsp;&nbsp; Here
703 
+we do the above search example using uids:</strong></p>
704 
+<div align="left">
705 
+
706 
+<pre>
707 
+user(9): (mb:search-mailbox mb '(:text &quot;blitzfig&quot;) :uid t)
708 
+(68)
709 
+user(10): (mb:fetch-field 68 &quot;body[]&quot; (mb:fetch-letter mb 68 &quot;body[]&quot; :uid t) :uid t)
710 
+&quot;Return-Path: &lt;jkf@verada.com&gt;
711 
+Received: from main.verada.com (main.verada.com [208.164.216.3])
712 
+&nbsp;&nbsp;&nbsp; by tiger.franz.com (8.8.7/8.8.7) with ESMTP id NAA20541
713 
+&nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:37:24 -0700
714 
+Received: from main.verada.com (IDENT:jkf@localhost [127.0.0.1])
715 
+&nbsp;&nbsp;&nbsp; by main.verada.com (8.9.3/8.9.3) with ESMTP id NAA06121
716 
+&nbsp;&nbsp;&nbsp; for &lt;jkfmail@tiger.franz.com&gt;; Mon, 13 Sep 1999 13:36:54 -0700
717 
+Message-Id: &lt;199909132036.NAA06121@main.verada.com&gt;
718 
+To: jkfmail@tiger.franz.com
719 
+Subject: s test
720 
+Date: Mon, 13 Sep 1999 13:36:54 -0700
721 
+From: jkf &lt;jkf@verada.com&gt;
722 
+
723 
+secret word: blitzfig
724 
+ok?
725 
+&quot;</pre>
726 
+</div>
727 
+
728 
+<p align="left"><strong>We'll delete that letter with the secret word and then note that
729 
+we have only six messages in the mailbox.</strong></p>
730 
+<div align="left">
731 
+
732 
+<pre>
733 
+user(11): (mb:delete-letter mb 68 :uid t)
734 
+(7)
735 
+user(12): (mb:mailbox-message-count mb)
736 
+6</pre>
737 
+</div>
738 
+
739 
+<p align="left"><strong>Now we assume that a bit of time has passed and we want to see if
740 
+any new messages have been delivered into the mailbox.&nbsp;&nbsp; In order to find out we
741 
+have to send a command to the imap server since it will only notify us of new messages
742 
+when it responds to a command.&nbsp;&nbsp; Since we have nothing to ask the imap server to
743 
+do we issue the noop command, which does nothing on the server.</strong></p>
744 
+<div align="left">
745 
+
746 
+<pre>
747 
+user(13): (mb:noop mb)
748 
+nil
749 
+user(14): (mb:mailbox-message-count mb)
750 
+7</pre>
751 
+</div>
752 
+
753 
+<p align="left"><strong>The server told us that there are now 7 messages in the inbox, one
754 
+more than before.&nbsp; Next we create a new mailbox, copy the messages from the inbox to
755 
+the new mailbox and then delete them from the inbox.&nbsp; Note how we use the :seq form
756 
+to specify a sequence of messages.</strong></p>
757 
+<div align="left">
758 
+
759 
+<pre>
760 
+user(15): (mb:create-mailbox mb &quot;tempbox&quot;)
761 
+t
762 
+user(18): (let ((count (mb:mailbox-message-count mb)))
763 
+(mb:copy-to-mailbox mb `(:seq 1 ,count) &quot;tempbox&quot;)
764 
+(mb:delete-letter mb `(:seq 1 ,count)))
765 
+(1 1 1 1 1 1 1)
766 
+user(19): (mb:mailbox-message-count mb)
767 
+0</pre>
768 
+</div>
769 
+
770 
+<p align="left"><strong>When we're done there are 0 messages in the currently selected
771 
+mailbox, which is inbox.&nbsp; We now select the maibox we just created and see that the
772 
+messages are there.</strong></p>
773 
+<div align="left">
774 
+
775 
+<pre>
776 
+user(22): (mb:select-mailbox mb &quot;tempbox&quot;)
777 
+t
778 
+user(23): (mb:mailbox-message-count mb)
779 
+7</pre>
780 
+</div>
781 
+
782 
+<p align="left"><strong>Finally we shut down the connection.&nbsp;&nbsp; Note that imap
783 
+servers will automatically shut down a connection that's been idle for too long (usually
784 
+around 10 minutes).&nbsp; When that happens, the next time the client tries to use an imap
785 
+function to access the mailbox an error will occur.&nbsp;&nbsp; There is nothing that can
786 
+be done to revive the connection however it is important to call close-imap-connection on
787 
+the lisp side in order to free up the resources still in use for the now dead connection.</strong></p>
788 
+<div align="left">
789 
+
790 
+<pre>
791 
+user(24): (mb:close-imap-connection mb)
792 
+t
793 
+</pre>
794 
+</div>
795 
+
796 
+<p align="left">&nbsp;</p>
797 
+
798 
+<p>&nbsp;</p>
799 
+</body>
800 
+</html>
imap.txt
History View file @ 5885760
0 801 
new file mode 100644
... ... 
@@ -0,0 +1,53 @@
1 
+ imap plan:
2 
+
3 
+flags:
4 
+    system flags are described in the imap protocol as
5 
+words like: \Answered
6 
+the backslash is annoying to type and I think that the
7 
+text is case insensitive anyway.
8 
+we'll represent these flags by keywords (e.g :answered).
9 
+
10 
+
11 
+
12 
+
13 
+
14 
+todo:
15 
+    uid (modifier to copy fetch and store commands)
16 
+
17 
+
18 
+
19 
+search sexpressions (things that can be passwd to the search-mailbox
20 
+function).
21 
+kwda - keywords that don't take any arguments
22 
+kwdb - keywords that do take arguments
23 
+
24 
+
25 
+ssexp :=  nil | ssexp1
26 
+ssexp1 := kwda | (kwdb oprnd+) (and ssexp1*) | (or ssexp1*) | (not ssexp1)
27 
+          | set
28 
+set := number-seq | ( number-seq+ )
29 
+number-seq := integer | (:seq integer integer)
30 
+kwda := :all | :answered ...
31 
+kwdb := :bcc | :before ....
32 
+oprnd := <the appropriate lisp object for the keyword>
33 
+
34 
+
35 
+
36 
+
37 
+
38 
+
39 
+
40 
+
41 
+implemented:
42 
+
43 
+  connecting:
44 
+    make-imap-connection
45 
+
46 
+  after connecting:
47 
+
48 
+    fetch-letter
49 
+    mailbox-list
50 
+    noop
51 
+    search-mailbox
52 
+    select-mailbox
53 
+
load.cl
History View file @ 5885760
0 54 
new file mode 100644
... ... 
@@ -0,0 +1,11 @@
1 
+(load (compile-file-if-needed "imap"))
2 
+(load (compile-file-if-needed "../smtp/smtp"))
3 
+
4 
+(defun test ()
5 
+  (setq *xx* (mb::make-imap-connection "tiger.franz.com"
6 
+				   :user "jkfmail"
7 
+				   :password "jkf.imap"
8 
+				   ))
9 
+  (mb::select-mailbox *xx* "inbox"))
10 
+
11 
+
rfc1939.html
History View file @ 5885760
0 12 
new file mode 100644
... ... 
@@ -0,0 +1,1303 @@
1 
+<HEAD>
2 
+<TITLE>rfc1939</TITLE>
3 
+</HEAD>
4 
+
5 
+<H1>rfc1939</H1>
6 
+Press <A NAME=id1 HREF="http://www.cis.ohio-state.edu/hypertext/information/rfc.html">here</A>
7 
+to go to the top of the rfc 'tree'.<p>
8 
+
9 
+<PRE>
10 
+
11 
+
12 
+
13 
+
14 
+
15 
+
16 
+Network Working Group                                           J. Myers
17 
+Request for Comments: <A NAME=id18 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                               Carnegie Mellon
18 
+STD: 53                                                          M. Rose
19 
+Obsoletes: <A NAME=id22 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1725.html">1725</A>                             Dover Beach Consulting, Inc.
20 
+Category: Standards Track                                       May <A NAME=id24 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1996.html">1996</A>
21 
+
22 
+
23 
+                    Post Office Protocol - Version 3
24 
+
25 
+Status of this Memo
26 
+
27 
+   This document specifies an Internet standards track protocol for the
28 
+   Internet community, and requests discussion and suggestions for
29 
+   improvements.  Please refer to the current edition of the "Internet
30 
+   Official Protocol Standards" (STD 1) for the standardization state
31 
+   and status of this protocol.  Distribution of this memo is unlimited.
32 
+
33 
+Table of Contents
34 
+
35 
+   1. Introduction ................................................    2
36 
+   2. A Short Digression ..........................................    2
37 
+   3. Basic Operation .............................................    3
38 
+   4. The AUTHORIZATION State .....................................    4
39 
+      QUIT Command ................................................    5
40 
+   5. The TRANSACTION State .......................................    5
41 
+      STAT Command ................................................    6
42 
+      LIST Command ................................................    6
43 
+      RETR Command ................................................    8
44 
+      DELE Command ................................................    8
45 
+      NOOP Command ................................................    9
46 
+      RSET Command ................................................    9
47 
+   6. The UPDATE State ............................................   10
48 
+      QUIT Command ................................................   10
49 
+   7. Optional POP3 Commands ......................................   11
50 
+      TOP Command .................................................   11
51 
+      UIDL Command ................................................   12
52 
+      USER Command ................................................   13
53 
+      PASS Command ................................................   14
54 
+      APOP Command ................................................   15
55 
+   8. Scaling and Operational Considerations ......................   16
56 
+   9. POP3 Command Summary ........................................   18
57 
+   10. Example POP3 Session .......................................   19
58 
+   11. Message Format .............................................   19
59 
+   12. References .................................................   20
60 
+   13. Security Considerations ....................................   20
61 
+   14. Acknowledgements ...........................................   20
62 
+   15. Authors' Addresses .........................................   21
63 
+   Appendix A. Differences from RFC <A NAME=id111 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1725.html">1725</A> ..........................   22
64 
+
65 
+
66 
+
67 
+Myers &#38; Rose                Standards Track                     [Page 1]
68 
+
69 
+RFC <A NAME=id123 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
70 
+
71 
+
72 
+   Appendix B. Command Index ......................................   23
73 
+
74 
+1. Introduction
75 
+
76 
+   On certain types of smaller nodes in the Internet it is often
77 
+   impractical to maintain a message transport system (MTS).  For
78 
+   example, a workstation may not have sufficient resources (cycles,
79 
+   disk space) in order to permit a SMTP server [RFC<A NAME=id144 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc821.html">821</A>] and associated
80 
+   local mail delivery system to be kept resident and continuously
81 
+   running.  Similarly, it may be expensive (or impossible) to keep a
82 
+   personal computer interconnected to an IP-style network for long
83 
+   amounts of time (the node is lacking the resource known as
84 
+   "connectivity").
85 
+
86 
+   Despite this, it is often very useful to be able to manage mail on
87 
+   these smaller nodes, and they often support a user agent (UA) to aid
88 
+   the tasks of mail handling.  To solve this problem, a node which can
89 
+   support an MTS entity offers a maildrop service to these less endowed
90 
+   nodes.  The Post Office Protocol - Version 3 (POP3) is intended to
91 
+   permit a workstation to dynamically access a maildrop on a server
92 
+   host in a useful fashion.  Usually, this means that the POP3 protocol
93 
+   is used to allow a workstation to retrieve mail that the server is
94 
+   holding for it.
95 
+
96 
+   POP3 is not intended to provide extensive manipulation operations of
97 
+   mail on the server; normally, mail is downloaded and then deleted.  A
98 
+   more advanced (and complex) protocol, IMAP4, is discussed in
99 
+   [RFC<A NAME=id185 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1730.html">1730</A>].
100 
+
101 
+   For the remainder of this memo, the term "client host" refers to a
102 
+   host making use of the POP3 service, while the term "server host"
103 
+   refers to a host which offers the POP3 service.
104 
+
105 
+2. A Short Digression
106 
+
107 
+   This memo does not specify how a client host enters mail into the
108 
+   transport system, although a method consistent with the philosophy of
109 
+   this memo is presented here:
110 
+
111 
+      When the user agent on a client host wishes to enter a message
112 
+      into the transport system, it establishes an SMTP connection to
113 
+      its relay host and sends all mail to it.  This relay host could
114 
+      be, but need not be, the POP3 server host for the client host.  Of
115 
+      course, the relay host must accept mail for delivery to arbitrary
116 
+      recipient addresses, that functionality is not required of all
117 
+      SMTP servers.
118 
+
119 
+
120 
+
121 
+
122 
+
123 
+Myers &#38; Rose                Standards Track                     [Page 2]
124 
+
125 
+RFC <A NAME=id237 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
126 
+
127 
+
128 
+3. Basic Operation
129 
+
130 
+   Initially, the server host starts the POP3 service by listening on
131 
+   TCP port 110.  When a client host wishes to make use of the service,
132 
+   it establishes a TCP connection with the server host.  When the
133 
+   connection is established, the POP3 server sends a greeting.  The
134 
+   client and POP3 server then exchange commands and responses
135 
+   (respectively) until the connection is closed or aborted.
136 
+
137 
+   Commands in the POP3 consist of a case-insensitive keyword, possibly
138 
+   followed by one or more arguments.  All commands are terminated by a
139 
+   CRLF pair.  Keywords and arguments consist of printable ASCII
140 
+   characters.  Keywords and arguments are each separated by a single
141 
+   SPACE character.  Keywords are three or four characters long. Each
142 
+   argument may be up to 40 characters long.
143 
+
144 
+   Responses in the POP3 consist of a status indicator and a keyword
145 
+   possibly followed by additional information.  All responses are
146 
+   terminated by a CRLF pair.  Responses may be up to 512 characters
147 
+   long, including the terminating CRLF.  There are currently two status
148 
+   indicators: positive ("+OK") and negative ("-ERR").  Servers MUST
149 
+   send the "+OK" and "-ERR" in upper case.
150 
+
151 
+   Responses to certain commands are multi-line.  In these cases, which
152 
+   are clearly indicated below, after sending the first line of the
153 
+   response and a CRLF, any additional lines are sent, each terminated
154 
+   by a CRLF pair.  When all lines of the response have been sent, a
155 
+   final line is sent, consisting of a termination octet (decimal code
156 
+   046, ".") and a CRLF pair.  If any line of the multi-line response
157 
+   begins with the termination octet, the line is "byte-stuffed" by
158 
+   pre-pending the termination octet to that line of the response.
159 
+   Hence a multi-line response is terminated with the five octets
160 
+   "CRLF.CRLF".  When examining a multi-line response, the client checks
161 
+   to see if the line begins with the termination octet.  If so and if
162 
+   octets other than CRLF follow, the first octet of the line (the
163 
+   termination octet) is stripped away.  If so and if CRLF immediately
164 
+   follows the termination character, then the response from the POP
165 
+   server is ended and the line containing ".CRLF" is not considered
166 
+   part of the multi-line response.
167 
+
168 
+   A POP3 session progresses through a number of states during its
169 
+   lifetime.  Once the TCP connection has been opened and the POP3
170 
+   server has sent the greeting, the session enters the AUTHORIZATION
171 
+   state.  In this state, the client must identify itself to the POP3
172 
+   server.  Once the client has successfully done this, the server
173 
+   acquires resources associated with the client's maildrop, and the
174 
+   session enters the TRANSACTION state.  In this state, the client
175 
+   requests actions on the part of the POP3 server.  When the client has
176 
+
177 
+
178 
+
179 
+Myers &#38; Rose                Standards Track                     [Page 3]
180 
+
181 
+RFC <A NAME=id349 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
182 
+
183 
+
184 
+   issued the QUIT command, the session enters the UPDATE state.  In
185 
+   this state, the POP3 server releases any resources acquired during
186 
+   the TRANSACTION state and says goodbye.  The TCP connection is then
187 
+   closed.
188 
+
189 
+   A server MUST respond to an unrecognized, unimplemented, or
190 
+   syntactically invalid command by responding with a negative status
191 
+   indicator.  A server MUST respond to a command issued when the
192 
+   session is in an incorrect state by responding with a negative status
193 
+   indicator.  There is no general method for a client to distinguish
194 
+   between a server which does not implement an optional command and a
195 
+   server which is unwilling or unable to process the command.
196 
+
197 
+   A POP3 server MAY have an inactivity autologout timer.  Such a timer
198 
+   MUST be of at least 10 minutes' duration.  The receipt of any command
199 
+   from the client during that interval should suffice to reset the
200 
+   autologout timer.  When the timer expires, the session does NOT enter
201 
+   the UPDATE state--the server should close the TCP connection without
202 
+   removing any messages or sending any response to the client.
203 
+
204 
+4. The AUTHORIZATION State
205 
+
206 
+   Once the TCP connection has been opened by a POP3 client, the POP3
207 
+   server issues a one line greeting.  This can be any positive
208 
+   response.  An example might be:
209 
+
210 
+      S:  +OK POP3 server ready
211 
+
212 
+   The POP3 session is now in the AUTHORIZATION state.  The client must
213 
+   now identify and authenticate itself to the POP3 server.  Two
214 
+   possible mechanisms for doing this are described in this document,
215 
+   the USER and PASS command combination and the APOP command.  Both
216 
+   mechanisms are described later in this document.  Additional
217 
+   authentication mechanisms are described in [RFC<A NAME=id422 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1734.html">1734</A>].  While there is
218 
+   no single authentication mechanism that is required of all POP3
219 
+   servers, a POP3 server must of course support at least one
220 
+   authentication mechanism.
221 
+
222 
+   Once the POP3 server has determined through the use of any
223 
+   authentication command that the client should be given access to the
224 
+   appropriate maildrop, the POP3 server then acquires an exclusive-
225 
+   access lock on the maildrop, as necessary to prevent messages from
226 
+   being modified or removed before the session enters the UPDATE state.
227 
+   If the lock is successfully acquired, the POP3 server responds with a
228 
+   positive status indicator.  The POP3 session now enters the
229 
+   TRANSACTION state, with no messages marked as deleted.  If the
230 
+   maildrop cannot be opened for some reason (for example, a lock can
231 
+   not be acquired, the client is denied access to the appropriate
232 
+
233 
+
234 
+
235 
+Myers &#38; Rose                Standards Track                     [Page 4]
236 
+
237 
+RFC <A NAME=id462 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
238 
+
239 
+
240 
+   maildrop, or the maildrop cannot be parsed), the POP3 server responds
241 
+   with a negative status indicator.  (If a lock was acquired but the
242 
+   POP3 server intends to respond with a negative status indicator, the
243 
+   POP3 server must release the lock prior to rejecting the command.)
244 
+   After returning a negative status indicator, the server may close the
245 
+   connection.  If the server does not close the connection, the client
246 
+   may either issue a new authentication command and start again, or the
247 
+   client may issue the QUIT command.
248 
+
249 
+   After the POP3 server has opened the maildrop, it assigns a message-
250 
+   number to each message, and notes the size of each message in octets.
251 
+   The first message in the maildrop is assigned a message-number of
252 
+   "1", the second is assigned "2", and so on, so that the nth message
253 
+   in a maildrop is assigned a message-number of "n".  In POP3 commands
254 
+   and responses, all message-numbers and message sizes are expressed in
255 
+   base-10 (i.e., decimal).
256 
+
257 
+   Here is the summary for the QUIT command when used in the
258 
+   AUTHORIZATION state:
259 
+
260 
+      QUIT
261 
+
262 
+         Arguments: none
263 
+
264 
+         Restrictions: none
265 
+
266 
+         Possible Responses:
267 
+             +OK
268 
+
269 
+         Examples:
270 
+             C: QUIT
271 
+             S: +OK dewey POP3 server signing off
272 
+
273 
+5. The TRANSACTION State
274 
+
275 
+   Once the client has successfully identified itself to the POP3 server
276 
+   and the POP3 server has locked and opened the appropriate maildrop,
277 
+   the POP3 session is now in the TRANSACTION state.  The client may now
278 
+   issue any of the following POP3 commands repeatedly.  After each
279 
+   command, the POP3 server issues a response.  Eventually, the client
280 
+   issues the QUIT command and the POP3 session enters the UPDATE state.
281 
+
282 
+
283 
+
284 
+
285 
+
286 
+
287 
+
288 
+
289 
+
290 
+
291 
+Myers &#38; Rose                Standards Track                     [Page 5]
292 
+
293 
+RFC <A NAME=id574 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
294 
+
295 
+
296 
+   Here are the POP3 commands valid in the TRANSACTION state:
297 
+
298 
+      STAT
299 
+
300 
+         Arguments: none
301 
+
302 
+         Restrictions:
303 
+             may only be given in the TRANSACTION state
304 
+
305 
+         Discussion:
306 
+             The POP3 server issues a positive response with a line
307 
+             containing information for the maildrop.  This line is
308 
+             called a "drop listing" for that maildrop.
309 
+
310 
+             In order to simplify parsing, all POP3 servers are
311 
+             required to use a certain format for drop listings.  The
312 
+             positive response consists of "+OK" followed by a single
313 
+             space, the number of messages in the maildrop, a single
314 
+             space, and the size of the maildrop in octets.  This memo
315 
+             makes no requirement on what follows the maildrop size.
316 
+             Minimal implementations should just end that line of the
317 
+             response with a CRLF pair.  More advanced implementations
318 
+             may include other information.
319 
+
320 
+                NOTE: This memo STRONGLY discourages implementations
321 
+                from supplying additional information in the drop
322 
+                listing.  Other, optional, facilities are discussed
323 
+                later on which permit the client to parse the messages
324 
+                in the maildrop.
325 
+
326 
+             Note that messages marked as deleted are not counted in
327 
+             either total.
328 
+
329 
+         Possible Responses:
330 
+             +OK nn mm
331 
+
332 
+         Examples:
333 
+             C: STAT
334 
+             S: +OK 2 320
335 
+
336 
+
337 
+      LIST [msg]
338 
+
339 
+         Arguments:
340 
+             a message-number (optional), which, if present, may NOT
341 
+             refer to a message marked as deleted
342 
+
343 
+
344 
+
345 
+
346 
+
347 
+Myers &#38; Rose                Standards Track                     [Page 6]
348 
+
349 
+RFC <A NAME=id686 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
350 
+
351 
+
352 
+         Restrictions:
353 
+             may only be given in the TRANSACTION state
354 
+
355 
+         Discussion:
356 
+             If an argument was given and the POP3 server issues a
357 
+             positive response with a line containing information for
358 
+             that message.  This line is called a "scan listing" for
359 
+             that message.
360 
+
361 
+             If no argument was given and the POP3 server issues a
362 
+             positive response, then the response given is multi-line.
363 
+             After the initial +OK, for each message in the maildrop,
364 
+             the POP3 server responds with a line containing
365 
+             information for that message.  This line is also called a
366 
+             "scan listing" for that message.  If there are no
367 
+             messages in the maildrop, then the POP3 server responds
368 
+             with no scan listings--it issues a positive response
369 
+             followed by a line containing a termination octet and a
370 
+             CRLF pair.
371 
+
372 
+             In order to simplify parsing, all POP3 servers are
373 
+             required to use a certain format for scan listings.  A
374 
+             scan listing consists of the message-number of the
375 
+             message, followed by a single space and the exact size of
376 
+             the message in octets.  Methods for calculating the exact
377 
+             size of the message are described in the "Message Format"
378 
+             section below.  This memo makes no requirement on what
379 
+             follows the message size in the scan listing.  Minimal
380 
+             implementations should just end that line of the response
381 
+             with a CRLF pair.  More advanced implementations may
382 
+             include other information, as parsed from the message.
383 
+
384 
+                NOTE: This memo STRONGLY discourages implementations
385 
+                from supplying additional information in the scan
386 
+                listing.  Other, optional, facilities are discussed
387 
+                later on which permit the client to parse the messages
388 
+                in the maildrop.
389 
+
390 
+             Note that messages marked as deleted are not listed.
391 
+
392 
+         Possible Responses:
393 
+             +OK scan listing follows
394 
+             -ERR no such message
395 
+
396 
+         Examples:
397 
+             C: LIST
398 
+             S: +OK 2 messages (320 octets)
399 
+             S: 1 120
400 
+
401 
+
402 
+
403 
+Myers &#38; Rose                Standards Track                     [Page 7]
404 
+
405 
+RFC <A NAME=id798 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
406 
+
407 
+
408 
+             S: 2 200
409 
+             S: .
410 
+               ...
411 
+             C: LIST 2
412 
+             S: +OK 2 200
413 
+               ...
414 
+             C: LIST 3
415 
+             S: -ERR no such message, only 2 messages in maildrop
416 
+
417 
+
418 
+      RETR msg
419 
+
420 
+         Arguments:
421 
+             a message-number (required) which may NOT refer to a
422 
+             message marked as deleted
423 
+
424 
+         Restrictions:
425 
+             may only be given in the TRANSACTION state
426 
+
427 
+         Discussion:
428 
+             If the POP3 server issues a positive response, then the
429 
+             response given is multi-line.  After the initial +OK, the
430 
+             POP3 server sends the message corresponding to the given
431 
+             message-number, being careful to byte-stuff the termination
432 
+             character (as with all multi-line responses).
433 
+
434 
+         Possible Responses:
435 
+             +OK message follows
436 
+             -ERR no such message
437 
+
438 
+         Examples:
439 
+             C: RETR 1
440 
+             S: +OK 120 octets
441 
+             S: &#60;the POP3 server sends the entire message here&#62;
442 
+             S: .
443 
+
444 
+
445 
+      DELE msg
446 
+
447 
+         Arguments:
448 
+             a message-number (required) which may NOT refer to a
449 
+             message marked as deleted
450 
+
451 
+         Restrictions:
452 
+             may only be given in the TRANSACTION state
453 
+
454 
+
455 
+
456 
+
457 
+
458 
+
459 
+Myers &#38; Rose                Standards Track                     [Page 8]
460 
+
461 
+RFC <A NAME=id910 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
462 
+
463 
+
464 
+         Discussion:
465 
+             The POP3 server marks the message as deleted.  Any future
466 
+             reference to the message-number associated with the message
467 
+             in a POP3 command generates an error.  The POP3 server does
468 
+             not actually delete the message until the POP3 session
469 
+             enters the UPDATE state.
470 
+
471 
+         Possible Responses:
472 
+             +OK message deleted
473 
+             -ERR no such message
474 
+
475 
+         Examples:
476 
+             C: DELE 1
477 
+             S: +OK message 1 deleted
478 
+                ...
479 
+             C: DELE 2
480 
+             S: -ERR message 2 already deleted
481 
+
482 
+
483 
+      NOOP
484 
+
485 
+         Arguments: none
486 
+
487 
+         Restrictions:
488 
+             may only be given in the TRANSACTION state
489 
+
490 
+         Discussion:
491 
+             The POP3 server does nothing, it merely replies with a
492 
+             positive response.
493 
+
494 
+         Possible Responses:
495 
+             +OK
496 
+
497 
+         Examples:
498 
+             C: NOOP
499 
+             S: +OK
500 
+
501 
+
502 
+      RSET
503 
+
504 
+         Arguments: none
505 
+
506 
+         Restrictions:
507 
+             may only be given in the TRANSACTION state
508 
+
509 
+         Discussion:
510 
+             If any messages have been marked as deleted by the POP3
511 
+             server, they are unmarked.  The POP3 server then replies
512 
+
513 
+
514 
+
515 
+Myers &#38; Rose                Standards Track                     [Page 9]
516 
+
517 
+RFC <A NAME=id1022 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
518 
+
519 
+
520 
+             with a positive response.
521 
+
522 
+         Possible Responses:
523 
+             +OK
524 
+
525 
+         Examples:
526 
+             C: RSET
527 
+             S: +OK maildrop has 2 messages (320 octets)
528 
+
529 
+6. The UPDATE State
530 
+
531 
+   When the client issues the QUIT command from the TRANSACTION state,
532 
+   the POP3 session enters the UPDATE state.  (Note that if the client
533 
+   issues the QUIT command from the AUTHORIZATION state, the POP3
534 
+   session terminates but does NOT enter the UPDATE state.)
535 
+
536 
+   If a session terminates for some reason other than a client-issued
537 
+   QUIT command, the POP3 session does NOT enter the UPDATE state and
538 
+   MUST not remove any messages from the maildrop.
539 
+
540 
+      QUIT
541 
+
542 
+         Arguments: none
543 
+
544 
+         Restrictions: none
545 
+
546 
+         Discussion:
547 
+             The POP3 server removes all messages marked as deleted
548 
+             from the maildrop and replies as to the status of this
549 
+             operation.  If there is an error, such as a resource
550 
+             shortage, encountered while removing messages, the
551 
+             maildrop may result in having some or none of the messages
552 
+             marked as deleted be removed.  In no case may the server
553 
+             remove any messages not marked as deleted.
554 
+
555 
+             Whether the removal was successful or not, the server
556 
+             then releases any exclusive-access lock on the maildrop
557 
+             and closes the TCP connection.
558 
+
559 
+         Possible Responses:
560 
+             +OK
561 
+             -ERR some deleted messages not removed
562 
+
563 
+         Examples:
564 
+             C: QUIT
565 
+             S: +OK dewey POP3 server signing off (maildrop empty)
566 
+                ...
567 
+             C: QUIT
568 
+
569 
+
570 
+
571 
+Myers &#38; Rose                Standards Track                    [Page 10]
572 
+
573 
+RFC <A NAME=id1134 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
574 
+
575 
+
576 
+             S: +OK dewey POP3 server signing off (2 messages left)
577 
+                ...
578 
+
579 
+7. Optional POP3 Commands
580 
+
581 
+   The POP3 commands discussed above must be supported by all minimal
582 
+   implementations of POP3 servers.
583 
+
584 
+   The optional POP3 commands described below permit a POP3 client
585 
+   greater freedom in message handling, while preserving a simple POP3
586 
+   server implementation.
587 
+
588 
+      NOTE: This memo STRONGLY encourages implementations to support
589 
+      these commands in lieu of developing augmented drop and scan
590 
+      listings.  In short, the philosophy of this memo is to put
591 
+      intelligence in the part of the POP3 client and not the POP3
592 
+      server.
593 
+
594 
+      TOP msg n
595 
+
596 
+         Arguments:
597 
+             a message-number (required) which may NOT refer to to a
598 
+             message marked as deleted, and a non-negative number
599 
+             of lines (required)
600 
+
601 
+         Restrictions:
602 
+             may only be given in the TRANSACTION state
603 
+
604 
+         Discussion:
605 
+             If the POP3 server issues a positive response, then the
606 
+             response given is multi-line.  After the initial +OK, the
607 
+             POP3 server sends the headers of the message, the blank
608 
+             line separating the headers from the body, and then the
609 
+             number of lines of the indicated message's body, being
610 
+             careful to byte-stuff the termination character (as with
611 
+             all multi-line responses).
612 
+
613 
+             Note that if the number of lines requested by the POP3
614 
+             client is greater than than the number of lines in the
615 
+             body, then the POP3 server sends the entire message.
616 
+
617 
+         Possible Responses:
618 
+             +OK top of message follows
619 
+             -ERR no such message
620 
+
621 
+         Examples:
622 
+             C: TOP 1 10
623 
+             S: +OK
624 
+
625 
+
626 
+
627 
+Myers &#38; Rose                Standards Track                    [Page 11]
628 
+
629 
+RFC <A NAME=id1246 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
630 
+
631 
+
632 
+             S: &#60;the POP3 server sends the headers of the
633 
+                message, a blank line, and the first 10 lines
634 
+                of the body of the message&#62;
635 
+             S: .
636 
+                ...
637 
+             C: TOP 100 3
638 
+             S: -ERR no such message
639 
+
640 
+
641 
+      UIDL [msg]
642 
+
643 
+      Arguments:
644 
+          a message-number (optional), which, if present, may NOT
645 
+          refer to a message marked as deleted
646 
+
647 
+      Restrictions:
648 
+          may only be given in the TRANSACTION state.
649 
+
650 
+      Discussion:
651 
+          If an argument was given and the POP3 server issues a positive
652 
+          response with a line containing information for that message.
653 
+          This line is called a "unique-id listing" for that message.
654 
+
655 
+          If no argument was given and the POP3 server issues a positive
656 
+          response, then the response given is multi-line.  After the
657 
+          initial +OK, for each message in the maildrop, the POP3 server
658 
+          responds with a line containing information for that message.
659 
+          This line is called a "unique-id listing" for that message.
660 
+
661 
+          In order to simplify parsing, all POP3 servers are required to
662 
+          use a certain format for unique-id listings.  A unique-id
663 
+          listing consists of the message-number of the message,
664 
+          followed by a single space and the unique-id of the message.
665 
+          No information follows the unique-id in the unique-id listing.
666 
+
667 
+          The unique-id of a message is an arbitrary server-determined
668 
+          string, consisting of one to 70 characters in the range 0x21
669 
+          to 0x7E, which uniquely identifies a message within a
670 
+          maildrop and which persists across sessions.  This
671 
+          persistence is required even if a session ends without
672 
+          entering the UPDATE state.  The server should never reuse an
673 
+          unique-id in a given maildrop, for as long as the entity
674 
+          using the unique-id exists.
675 
+
676 
+          Note that messages marked as deleted are not listed.
677 
+
678 
+          While it is generally preferable for server implementations
679 
+          to store arbitrarily assigned unique-ids in the maildrop,
680 
+
681 
+
682 
+
683 
+Myers &#38; Rose                Standards Track                    [Page 12]
684 
+
685 
+RFC <A NAME=id1358 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
686 
+
687 
+
688 
+          this specification is intended to permit unique-ids to be
689 
+          calculated as a hash of the message.  Clients should be able
690 
+          to handle a situation where two identical copies of a
691 
+          message in a maildrop have the same unique-id.
692 
+
693 
+      Possible Responses:
694 
+          +OK unique-id listing follows
695 
+          -ERR no such message
696 
+
697 
+      Examples:
698 
+          C: UIDL
699 
+          S: +OK
700 
+          S: 1 whqtswO00WBw418f9t5JxYwZ
701 
+          S: 2 QhdPYR:00WBw1Ph7x7
702 
+          S: .
703 
+             ...
704 
+          C: UIDL 2
705 
+          S: +OK 2 QhdPYR:00WBw1Ph7x7
706 
+             ...
707 
+          C: UIDL 3
708 
+          S: -ERR no such message, only 2 messages in maildrop
709 
+
710 
+
711 
+      USER name
712 
+
713 
+         Arguments:
714 
+             a string identifying a mailbox (required), which is of
715 
+             significance ONLY to the server
716 
+
717 
+         Restrictions:
718 
+             may only be given in the AUTHORIZATION state after the POP3
719 
+             greeting or after an unsuccessful USER or PASS command
720 
+
721 
+         Discussion:
722 
+             To authenticate using the USER and PASS command
723 
+             combination, the client must first issue the USER
724 
+             command.  If the POP3 server responds with a positive
725 
+             status indicator ("+OK"), then the client may issue
726 
+             either the PASS command to complete the authentication,
727 
+             or the QUIT command to terminate the POP3 session.  If
728 
+             the POP3 server responds with a negative status indicator
729 
+             ("-ERR") to the USER command, then the client may either
730 
+             issue a new authentication command or may issue the QUIT
731 
+             command.
732 
+
733 
+             The server may return a positive response even though no
734 
+             such mailbox exists.  The server may return a negative
735 
+             response if mailbox exists, but does not permit plaintext
736 
+
737 
+
738 
+
739 
+Myers &#38; Rose                Standards Track                    [Page 13]
740 
+
741 
+RFC <A NAME=id1470 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
742 
+
743 
+
744 
+             password authentication.
745 
+
746 
+         Possible Responses:
747 
+             +OK name is a valid mailbox
748 
+             -ERR never heard of mailbox name
749 
+
750 
+         Examples:
751 
+             C: USER frated
752 
+             S: -ERR sorry, no mailbox for frated here
753 
+                ...
754 
+             C: USER mrose
755 
+             S: +OK mrose is a real hoopy frood
756 
+
757 
+
758 
+      PASS string
759 
+
760 
+         Arguments:
761 
+             a server/mailbox-specific password (required)
762 
+
763 
+         Restrictions:
764 
+             may only be given in the AUTHORIZATION state immediately
765 
+             after a successful USER command
766 
+
767 
+         Discussion:
768 
+             When the client issues the PASS command, the POP3 server
769 
+             uses the argument pair from the USER and PASS commands to
770 
+             determine if the client should be given access to the
771 
+             appropriate maildrop.
772 
+
773 
+             Since the PASS command has exactly one argument, a POP3
774 
+             server may treat spaces in the argument as part of the
775 
+             password, instead of as argument separators.
776 
+
777 
+         Possible Responses:
778 
+             +OK maildrop locked and ready
779 
+             -ERR invalid password
780 
+             -ERR unable to lock maildrop
781 
+
782 
+         Examples:
783 
+             C: USER mrose
784 
+             S: +OK mrose is a real hoopy frood
785 
+             C: PASS secret
786 
+             S: -ERR maildrop already locked
787 
+               ...
788 
+             C: USER mrose
789 
+             S: +OK mrose is a real hoopy frood
790 
+             C: PASS secret
791 
+             S: +OK mrose's maildrop has 2 messages (320 octets)
792 
+
793 
+
794 
+
795 
+Myers &#38; Rose                Standards Track                    [Page 14]
796 
+
797 
+RFC <A NAME=id1582 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
798 
+
799 
+
800 
+      APOP name digest
801 
+
802 
+         Arguments:
803 
+             a string identifying a mailbox and a MD5 digest string
804 
+             (both required)
805 
+
806 
+         Restrictions:
807 
+             may only be given in the AUTHORIZATION state after the POP3
808 
+             greeting or after an unsuccessful USER or PASS command
809 
+
810 
+         Discussion:
811 
+             Normally, each POP3 session starts with a USER/PASS
812 
+             exchange.  This results in a server/user-id specific
813 
+             password being sent in the clear on the network.  For
814 
+             intermittent use of POP3, this may not introduce a sizable
815 
+             risk.  However, many POP3 client implementations connect to
816 
+             the POP3 server on a regular basis -- to check for new
817 
+             mail.  Further the interval of session initiation may be on
818 
+             the order of five minutes.  Hence, the risk of password
819 
+             capture is greatly enhanced.
820 
+
821 
+             An alternate method of authentication is required which
822 
+             provides for both origin authentication and replay
823 
+             protection, but which does not involve sending a password
824 
+             in the clear over the network.  The APOP command provides
825 
+             this functionality.
826 
+
827 
+             A POP3 server which implements the APOP command will
828 
+             include a timestamp in its banner greeting.  The syntax of
829 
+             the timestamp corresponds to the `msg-id' in [RFC<A NAME=id1647 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc822.html">822</A>], and
830 
+             MUST be different each time the POP3 server issues a banner
831 
+             greeting.  For example, on a UNIX implementation in which a
832 
+             separate UNIX process is used for each instance of a POP3
833 
+             server, the syntax of the timestamp might be:
834 
+
835 
+                &#60;process-ID.clock@hostname&#62;
836 
+
837 
+             where `process-ID' is the decimal value of the process's
838 
+             PID, clock is the decimal value of the system clock, and
839 
+             hostname is the fully-qualified domain-name corresponding
840 
+             to the host where the POP3 server is running.
841 
+
842 
+             The POP3 client makes note of this timestamp, and then
843 
+             issues the APOP command.  The `name' parameter has
844 
+             identical semantics to the `name' parameter of the USER
845 
+             command. The `digest' parameter is calculated by applying
846 
+             the MD5 algorithm [RFC<A NAME=id1682 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1321.html">1321</A>] to a string consisting of the
847 
+             timestamp (including angle-brackets) followed by a shared
848 
+
849 
+
850 
+
851 
+Myers &#38; Rose                Standards Track                    [Page 15]
852 
+
853 
+RFC <A NAME=id1696 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
854 
+
855 
+
856 
+             secret.  This shared secret is a string known only to the
857 
+             POP3 client and server.  Great care should be taken to
858 
+             prevent unauthorized disclosure of the secret, as knowledge
859 
+             of the secret will allow any entity to successfully
860 
+             masquerade as the named user.  The `digest' parameter
861 
+             itself is a 16-octet value which is sent in hexadecimal
862 
+             format, using lower-case ASCII characters.
863 
+
864 
+             When the POP3 server receives the APOP command, it verifies
865 
+             the digest provided.  If the digest is correct, the POP3
866 
+             server issues a positive response, and the POP3 session
867 
+             enters the TRANSACTION state.  Otherwise, a negative
868 
+             response is issued and the POP3 session remains in the
869 
+             AUTHORIZATION state.
870 
+
871 
+             Note that as the length of the shared secret increases, so
872 
+             does the difficulty of deriving it.  As such, shared
873 
+             secrets should be long strings (considerably longer than
874 
+             the 8-character example shown below).
875 
+
876 
+         Possible Responses:
877 
+             +OK maildrop locked and ready
878 
+             -ERR permission denied
879 
+
880 
+         Examples:
881 
+             S: +OK POP3 server ready &#60;1896.697170952@dbc.mtview.ca.us&#62;
882 
+             C: APOP mrose c4c9334bac560ecc979e58001b3e22fb
883 
+             S: +OK maildrop has 1 message (369 octets)
884 
+
885 
+             In this example, the shared  secret  is  the  string  `tan-
886 
+             staaf'.  Hence, the MD5 algorithm is applied to the string
887 
+
888 
+                &#60;1896.697170952@dbc.mtview.ca.us&#62;tanstaaf
889 
+
890 
+             which produces a digest value of
891 
+
892 
+                c4c9334bac560ecc979e58001b3e22fb
893 
+
894 
+8. Scaling and Operational Considerations
895 
+
896 
+   Since some of the optional features described above were added to the
897 
+   POP3 protocol, experience has accumulated in using them in large-
898 
+   scale commercial post office operations where most of the users are
899 
+   unrelated to each other.  In these situations and others, users and
900 
+   vendors of POP3 clients have discovered that the combination of using
901 
+   the UIDL command and not issuing the DELE command can provide a weak
902 
+   version of the "maildrop as semi-permanent repository" functionality
903 
+   normally associated with IMAP.  Of course the other capabilities of
904 
+
905 
+
906 
+
907 
+Myers &#38; Rose                Standards Track                    [Page 16]
908 
+
909 
+RFC <A NAME=id1808 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
910 
+
911 
+
912 
+   IMAP, such as polling an existing connection for newly arrived
913 
+   messages and supporting multiple folders on the server, are not
914 
+   present in POP3.
915 
+
916 
+   When these facilities are used in this way by casual users, there has
917 
+   been a tendency for already-read messages to accumulate on the server
918 
+   without bound.  This is clearly an undesirable behavior pattern from
919 
+   the standpoint of the server operator.  This situation is aggravated
920 
+   by the fact that the limited capabilities of the POP3 do not permit
921 
+   efficient handling of maildrops which have hundreds or thousands of
922 
+   messages.
923 
+
924 
+   Consequently, it is recommended that operators of large-scale multi-
925 
+   user servers, especially ones in which the user's only access to the
926 
+   maildrop is via POP3, consider such options as:
927 
+
928 
+   *  Imposing a per-user maildrop storage quota or the like.
929 
+
930 
+      A disadvantage to this option is that accumulation of messages may
931 
+      result in the user's inability to receive new ones into the
932 
+      maildrop.  Sites which choose this option should be sure to inform
933 
+      users of impending or current exhaustion of quota, perhaps by
934 
+      inserting an appropriate message into the user's maildrop.
935 
+
936 
+   *  Enforce a site policy regarding mail retention on the server.
937 
+
938 
+      Sites are free to establish local policy regarding the storage and
939 
+      retention of messages on the server, both read and unread.  For
940 
+      example, a site might delete unread messages from the server after
941 
+      60 days and delete read messages after 7 days.  Such message
942 
+      deletions are outside the scope of the POP3 protocol and are not
943 
+      considered a protocol violation.
944 
+
945 
+      Server operators enforcing message deletion policies should take
946 
+      care to make all users aware of the policies in force.
947 
+
948 
+      Clients must not assume that a site policy will automate message
949 
+      deletions, and should continue to explicitly delete messages using
950 
+      the DELE command when appropriate.
951 
+
952 
+      It should be noted that enforcing site message deletion policies
953 
+      may be confusing to the user community, since their POP3 client
954 
+      may contain configuration options to leave mail on the server
955 
+      which will not in fact be supported by the server.
956 
+
957 
+      One special case of a site policy is that messages may only be
958 
+      downloaded once from the server, and are deleted after this has
959 
+      been accomplished.  This could be implemented in POP3 server
960 
+
961 
+
962 
+
963 
+Myers &#38; Rose                Standards Track                    [Page 17]
964 
+
965 
+RFC <A NAME=id1920 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
966 
+
967 
+
968 
+      software by the following mechanism: "following a POP3 login by a
969 
+      client which was ended by a QUIT, delete all messages downloaded
970 
+      during the session with the RETR command".  It is important not to
971 
+      delete messages in the event of abnormal connection termination
972 
+      (ie, if no QUIT was received from the client) because the client
973 
+      may not have successfully received or stored the messages.
974 
+      Servers implementing a download-and-delete policy may also wish to
975 
+      disable or limit the optional TOP command, since it could be used
976 
+      as an alternate mechanism to download entire messages.
977 
+
978 
+9. POP3 Command Summary
979 
+
980 
+      Minimal POP3 Commands:
981 
+
982 
+         USER name               valid in the AUTHORIZATION state
983 
+         PASS string
984 
+         QUIT
985 
+
986 
+         STAT                    valid in the TRANSACTION state
987 
+         LIST [msg]
988 
+         RETR msg
989 
+         DELE msg
990 
+         NOOP
991 
+         RSET
992 
+         QUIT
993 
+
994 
+      Optional POP3 Commands:
995 
+
996 
+         APOP name digest        valid in the AUTHORIZATION state
997 
+
998 
+         TOP msg n               valid in the TRANSACTION state
999 
+         UIDL [msg]
1000 
+
1001 
+      POP3 Replies:
1002 
+
1003 
+         +OK
1004 
+         -ERR
1005 
+
1006 
+      Note that with the exception of the STAT, LIST, and UIDL commands,
1007 
+      the reply given by the POP3 server to any command is significant
1008 
+      only to "+OK" and "-ERR".  Any text occurring after this reply
1009 
+      may be ignored by the client.
1010 
+
1011 
+
1012 
+
1013 
+
1014 
+
1015 
+
1016 
+
1017 
+
1018 
+
1019 
+Myers &#38; Rose                Standards Track                    [Page 18]
1020 
+
1021 
+RFC <A NAME=id2032 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
1022 
+
1023 
+
1024 
+10. Example POP3 Session
1025 
+
1026 
+      S: &#60;wait for connection on TCP port 110&#62;
1027 
+      C: &#60;open connection&#62;
1028 
+      S:    +OK POP3 server ready &#60;1896.697170952@dbc.mtview.ca.us&#62;
1029 
+      C:    APOP mrose c4c9334bac560ecc979e58001b3e22fb
1030 
+      S:    +OK mrose's maildrop has 2 messages (320 octets)
1031 
+      C:    STAT
1032 
+      S:    +OK 2 320
1033 
+      C:    LIST
1034 
+      S:    +OK 2 messages (320 octets)
1035 
+      S:    1 120
1036 
+      S:    2 200
1037 
+      S:    .
1038 
+      C:    RETR 1
1039 
+      S:    +OK 120 octets
1040 
+      S:    &#60;the POP3 server sends message 1&#62;
1041 
+      S:    .
1042 
+      C:    DELE 1
1043 
+      S:    +OK message 1 deleted
1044 
+      C:    RETR 2
1045 
+      S:    +OK 200 octets
1046 
+      S:    &#60;the POP3 server sends message 2&#62;
1047 
+      S:    .
1048 
+      C:    DELE 2
1049 
+      S:    +OK message 2 deleted
1050 
+      C:    QUIT
1051 
+      S:    +OK dewey POP3 server signing off (maildrop empty)
1052 
+      C:  &#60;close connection&#62;
1053 
+      S:  &#60;wait for next connection&#62;
1054 
+
1055 
+11. Message Format
1056 
+
1057 
+   All messages transmitted during a POP3 session are assumed to conform
1058 
+   to the standard for the format of Internet text messages [RFC<A NAME=id2107 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc822.html">822</A>].
1059 
+
1060 
+   It is important to note that the octet count for a message on the
1061 
+   server host may differ from the octet count assigned to that message
1062 
+   due to local conventions for designating end-of-line.  Usually,
1063 
+   during the AUTHORIZATION state of the POP3 session, the POP3 server
1064 
+   can calculate the size of each message in octets when it opens the
1065 
+   maildrop.  For example, if the POP3 server host internally represents
1066 
+   end-of-line as a single character, then the POP3 server simply counts
1067 
+   each occurrence of this character in a message as two octets.  Note
1068 
+   that lines in the message which start with the termination octet need
1069 
+   not (and must not) be counted twice, since the POP3 client will
1070 
+   remove all byte-stuffed termination characters when it receives a
1071 
+   multi-line response.
1072 
+
1073 
+
1074 
+
1075 
+Myers &#38; Rose                Standards Track                    [Page 19]
1076 
+
1077 
+RFC <A NAME=id2145 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
1078 
+
1079 
+
1080 
+12. References
1081 
+
1082 
+   [RFC<A NAME=id2156 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc821.html">821</A>] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
1083 
+       821, USC/Information Sciences Institute, August 1982.
1084 
+
1085 
+   [RFC<A NAME=id2163 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc822.html">822</A>] Crocker, D., "Standard for the Format of ARPA-Internet Text
1086 
+       Messages", STD 11, RFC <A NAME=id2166 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc822.html">822</A>, University of Delaware, August 1982.
1087 
+
1088 
+   [RFC<A NAME=id2172 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1321.html">1321</A>] Rivest, R., "The MD5 Message-Digest Algorithm", RFC <A NAME=id2171 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1321.html">1321</A>,
1089 
+       MIT Laboratory for Computer Science, April 1992.
1090 
+
1091 
+   [RFC<A NAME=id2179 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1730.html">1730</A>] Crispin, M., "Internet Message Access Protocol - Version
1092 
+       4", RFC <A NAME=id2182 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1730.html">1730</A>, University of Washington, December 1994.
1093 
+
1094 
+   [RFC<A NAME=id2188 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1734.html">1734</A>] Myers, J., "POP3 AUTHentication command", RFC <A NAME=id2187 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1734.html">1734</A>,
1095 
+       Carnegie Mellon, December 1994.
1096 
+
1097 
+13. Security Considerations
1098 
+
1099 
+   It is conjectured that use of the APOP command provides origin
1100 
+   identification and replay protection for a POP3 session.
1101 
+   Accordingly, a POP3 server which implements both the PASS and APOP
1102 
+   commands should not allow both methods of access for a given user;
1103 
+   that is, for a given mailbox name, either the USER/PASS command
1104 
+   sequence or the APOP command is allowed, but not both.
1105 
+
1106 
+   Further, note that as the length of the shared secret increases, so
1107 
+   does the difficulty of deriving it.
1108 
+
1109 
+   Servers that answer -ERR to the USER command are giving potential
1110 
+   attackers clues about which names are valid.
1111 
+
1112 
+   Use of the PASS command sends passwords in the clear over the
1113 
+   network.
1114 
+
1115 
+   Use of the RETR and TOP commands sends mail in the clear over the
1116 
+   network.
1117 
+
1118 
+   Otherwise, security issues are not discussed in this memo.
1119 
+
1120 
+14. Acknowledgements
1121 
+
1122 
+   The POP family has a long and checkered history.  Although primarily
1123 
+   a minor revision to RFC <A NAME=id2247 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1460.html">1460</A>, POP3 is based on the ideas presented in
1124 
+   RFCs 918, 937, and 1081.
1125 
+
1126 
+   In addition, Alfred Grimstad, Keith McCloghrie, and Neil Ostroff
1127 
+   provided significant comments on the APOP command.
1128 
+
1129 
+
1130 
+
1131 
+Myers &#38; Rose                Standards Track                    [Page 20]
1132 
+
1133 
+RFC <A NAME=id2267 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
1134 
+
1135 
+
1136 
+15. Authors' Addresses
1137 
+
1138 
+   John G. Myers
1139 
+   Carnegie-Mellon University
1140 
+   5000 Forbes Ave
1141 
+   Pittsburgh, PA 15213
1142 
+
1143 
+   EMail: jgm+@cmu.edu
1144 
+
1145 
+
1146 
+   Marshall T. Rose
1147 
+   Dover Beach Consulting, Inc.
1148 
+   420 Whisman Court
1149 
+   Mountain View, CA  94043-2186
1150 
+
1151 
+   EMail: mrose@dbc.mtview.ca.us
1152 
+
1153 
+
1154 
+
1155 
+
1156 
+
1157 
+
1158 
+
1159 
+
1160 
+
1161 
+
1162 
+
1163 
+
1164 
+
1165 
+
1166 
+
1167 
+
1168 
+
1169 
+
1170 
+
1171 
+
1172 
+
1173 
+
1174 
+
1175 
+
1176 
+
1177 
+
1178 
+
1179 
+
1180 
+
1181 
+
1182 
+
1183 
+
1184 
+
1185 
+
1186 
+
1187 
+Myers &#38; Rose                Standards Track                    [Page 21]
1188 
+
1189 
+RFC <A NAME=id2379 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
1190 
+
1191 
+
1192 
+Appendix A. Differences from RFC <A NAME=id2386 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1725.html">1725</A>
1193 
+
1194 
+   This memo is a revision to RFC <A NAME=id2391 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1725.html">1725</A>, a Draft Standard.  It makes the
1195 
+   following changes from that document:
1196 
+
1197 
+      - clarifies that command keywords are case insensitive.
1198 
+
1199 
+      - specifies that servers must send "+OK" and "-ERR" in
1200 
+        upper case.
1201 
+
1202 
+      - specifies that the initial greeting is a positive response,
1203 
+        instead of any string which should be a positive response.
1204 
+
1205 
+      - clarifies behavior for unimplemented commands.
1206 
+
1207 
+      - makes the USER and PASS commands optional.
1208 
+
1209 
+      - clarified the set of possible responses to the USER command.
1210 
+
1211 
+      - reverses the order of the examples in the USER and PASS
1212 
+        commands, to reduce confusion.
1213 
+
1214 
+      - clarifies that the PASS command may only be given immediately
1215 
+        after a successful USER command.
1216 
+
1217 
+      - clarified the persistence requirements of UIDs and added some
1218 
+        implementation notes.
1219 
+
1220 
+      - specifies a UID length limitation of one to 70 octets.
1221 
+
1222 
+      - specifies a status indicator length limitation
1223 
+        of 512 octets, including the CRLF.
1224 
+
1225 
+      - clarifies that LIST with no arguments on an empty mailbox
1226 
+        returns success.
1227 
+
1228 
+      - adds a reference from the LIST command to the Message Format
1229 
+        section
1230 
+
1231 
+      - clarifies the behavior of QUIT upon failure
1232 
+
1233 
+      - clarifies the security section to not imply the use of the
1234 
+        USER command with the APOP command.
1235 
+
1236 
+      - adds references to RFCs 1730 and 1734
1237 
+
1238 
+      - clarifies the method by which a UA may enter mail into the
1239 
+        transport system.
1240 
+
1241 
+
1242 
+
1243 
+Myers &#38; Rose                Standards Track                    [Page 22]
1244 
+
1245 
+RFC <A NAME=id2493 HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1939.html">1939</A>                          POP3                          May 1996
1246 
+
1247 
+
1248 
+      - clarifies that the second argument to the TOP command is a
1249 
+        number of lines.
1250 
+
1251 
+      - changes the suggestion in the Security Considerations section
1252 
+        for a server to not accept both PASS and APOP for a given user
1253 
+        from a "must" to a "should".
1254 
+
1255 
+      - adds a section on scaling and operational considerations
1256 
+
1257 
+Appendix B. Command Index
1258 
+
1259 
+       APOP .......................................................   15
1260 
+       DELE .......................................................    8
1261 
+       LIST .......................................................    6
1262 
+       NOOP .......................................................    9
1263 
+       PASS .......................................................   14
1264 
+       QUIT .......................................................    5
1265 
+       QUIT .......................................................   10
1266 
+       RETR .......................................................    8
1267 
+       RSET .......................................................    9
1268 
+       STAT .......................................................    6
1269 
+       TOP ........................................................   11
1270 
+       UIDL .......................................................   12
1271 
+       USER .......................................................   13
1272 
+
1273 
+
1274 
+
1275 
+
1276 
+
1277 
+
1278 
+
1279 
+
1280 
+
1281 
+
1282 
+
1283 
+
1284 
+
1285 
+
1286 
+
1287 
+
1288 
+
1289 
+
1290 
+
1291 
+
1292 
+
1293 
+
1294 
+
1295 
+
1296 
+
1297 
+
1298 
+
1299 
+Myers &#38; Rose                Standards Track                    [Page 23]
1300 
+
1301 
+</PRE>
1302 
+</BODY>
1303 
+</HTML>
rfc2060.txt
History View file @ 5885760
0 1304 
new file mode 100644
... ... 
@@ -0,0 +1,4595 @@
1 
+
2 
+
3 
+
4 
+
5 
+
6 
+
7 
+Network Working Group                                        M. Crispin
8 
+Request for Comments: 2060                     University of Washington
9 
+Obsoletes: 1730                                           December 1996
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 
+Abstract
24 
+
25 
+   The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1)
26 
+   allows a client to access and manipulate electronic mail messages on
27 
+   a server.  IMAP4rev1 permits manipulation of remote message folders,
28 
+   called "mailboxes", in a way that is functionally equivalent to local
29 
+   mailboxes.  IMAP4rev1 also provides the capability for an offline
30 
+   client to resynchronize with the server (see also [IMAP-DISC]).
31 
+
32 
+   IMAP4rev1 includes operations for creating, deleting, and renaming
33 
+   mailboxes; checking for new messages; permanently removing messages;
34 
+   setting and clearing flags; [RFC-822] and [MIME-IMB] parsing;
35 
+   searching; and selective fetching of message attributes, texts, and
36 
+   portions thereof.  Messages in IMAP4rev1 are accessed by the use of
37 
+   numbers.  These numbers are either message sequence numbers or unique
38 
+   identifiers.
39 
+
40 
+   IMAP4rev1 supports a single server.  A mechanism for accessing
41 
+   configuration information to support multiple IMAP4rev1 servers is
42 
+   discussed in [ACAP].
43 
+
44 
+   IMAP4rev1 does not specify a means of posting mail; this function is
45 
+   handled by a mail transfer protocol such as [SMTP].
46 
+
47 
+   IMAP4rev1 is designed to be upwards compatible from the [IMAP2] and
48 
+   unpublished IMAP2bis protocols.  In the course of the evolution of
49 
+   IMAP4rev1, some aspects in the earlier protocol have become obsolete.
50 
+   Obsolete commands, responses, and data formats which an IMAP4rev1
51 
+   implementation may encounter when used with an earlier implementation
52 
+   are described in [IMAP-OBSOLETE].
53 
+
54 
+
55 
+
56 
+
57 
+
58 
+Crispin                     Standards Track                     [Page 1]
59 
+
60 
+RFC 2060                       IMAP4rev1                   December 1996
61 
+
62 
+
63 
+   Other compatibility issues with IMAP2bis, the most common variant of
64 
+   the earlier protocol, are discussed in [IMAP-COMPAT].  A full
65 
+   discussion of compatibility issues with rare (and presumed extinct)
66 
+   variants of [IMAP2] is in [IMAP-HISTORICAL]; this document is
67 
+   primarily of historical interest.
68 
+
69 
+Table of Contents
70 
+
71 
+IMAP4rev1 Protocol Specification ..................................    4
72 
+1.      How to Read This Document .................................    4
73 
+1.1.    Organization of This Document .............................    4
74 
+1.2.    Conventions Used in This Document .........................    4
75 
+2.      Protocol Overview .........................................    5
76 
+2.1.    Link Level ................................................    5
77 
+2.2.    Commands and Responses ....................................    6
78 
+2.2.1.  Client Protocol Sender and Server Protocol Receiver .......    6
79 
+2.2.2.  Server Protocol Sender and Client Protocol Receiver .......    7
80 
+2.3.    Message Attributes ........................................    7
81 
+2.3.1.  Message Numbers ...........................................    7
82 
+2.3.1.1.        Unique Identifier (UID) Message Attribute .........    7
83 
+2.3.1.2.        Message Sequence Number Message Attribute .........    9
84 
+2.3.2.  Flags Message Attribute ....................................   9
85 
+2.3.3.  Internal Date Message Attribute ...........................   10
86 
+2.3.4.  [RFC-822] Size Message Attribute ..........................   11
87 
+2.3.5.  Envelope Structure Message Attribute ......................   11
88 
+2.3.6.  Body Structure Message Attribute ..........................   11
89 
+2.4.    Message Texts .............................................   11
90 
+3.      State and Flow Diagram ....................................   11
91 
+3.1.    Non-Authenticated State ...................................   11
92 
+3.2.    Authenticated State .......................................   11
93 
+3.3.    Selected State ............................................   12
94 
+3.4.    Logout State ..............................................   12
95 
+4.      Data Formats ..............................................   12
96 
+4.1.    Atom ......................................................   13
97 
+4.2.    Number ....................................................   13
98 
+4.3.    String .....................................................  13
99 
+4.3.1.  8-bit and Binary Strings ..................................   13
100 
+4.4.    Parenthesized List ........................................   14
101 
+4.5.    NIL .......................................................   14
102 
+5.      Operational Considerations ................................   14
103 
+5.1.    Mailbox Naming ............................................   14
104 
+5.1.1.  Mailbox Hierarchy Naming ..................................   14
105 
+5.1.2.  Mailbox Namespace Naming Convention .......................   14
106 
+5.1.3.  Mailbox International Naming Convention ...................   15
107 
+5.2.    Mailbox Size and Message Status Updates ...................   16
108 
+5.3.    Response when no Command in Progress ......................   16
109 
+5.4.    Autologout Timer ..........................................   16
110 
+5.5.    Multiple Commands in Progress .............................   17
111 
+
112 
+
113 
+
114 
+Crispin                     Standards Track                     [Page 2]
115 
+
116 
+RFC 2060                       IMAP4rev1                   December 1996
117 
+
118 
+
119 
+6.      Client Commands ...........................................   17
120 
+6.1.    Client Commands - Any State ...............................   18
121 
+6.1.1.  CAPABILITY Command ........................................   18
122 
+6.1.2.  NOOP Command ..............................................   19
123 
+6.1.3.  LOGOUT Command ............................................   20
124 
+6.2.    Client Commands - Non-Authenticated State .................   20
125 
+6.2.1.  AUTHENTICATE Command ......................................   21
126 
+6.2.2.  LOGIN Command .............................................   22
127 
+6.3.    Client Commands - Authenticated State .....................   22
128 
+6.3.1.  SELECT Command ............................................   23
129 
+6.3.2.  EXAMINE Command ...........................................   24
130 
+6.3.3.  CREATE Command ............................................   25
131 
+6.3.4.  DELETE Command ............................................   26
132 
+6.3.5.  RENAME Command ............................................   27
133 
+6.3.6.  SUBSCRIBE Command .........................................   29
134 
+6.3.7.  UNSUBSCRIBE Command .......................................   30
135 
+6.3.8.  LIST Command ..............................................   30
136 
+6.3.9.  LSUB Command ..............................................   32
137 
+6.3.10. STATUS Command ............................................   33
138 
+6.3.11. APPEND Command ............................................   34
139 
+6.4.    Client Commands - Selected State ..........................   35
140 
+6.4.1.  CHECK Command .............................................   36
141 
+6.4.2.  CLOSE Command .............................................   36
142 
+6.4.3.  EXPUNGE Command ...........................................   37
143 
+6.4.4.  SEARCH Command ............................................   37
144 
+6.4.5.  FETCH Command .............................................   41
145 
+6.4.6.  STORE Command .............................................   45
146 
+6.4.7.  COPY Command ..............................................   46
147 
+6.4.8.  UID Command ...............................................   47
148 
+6.5.    Client Commands - Experimental/Expansion ..................   48
149 
+6.5.1.  X<atom> Command ...........................................   48
150 
+7.      Server Responses ..........................................   48
151 
+7.1.    Server Responses - Status Responses .......................   49
152 
+7.1.1.  OK Response ...............................................   51
153 
+7.1.2.  NO Response ...............................................   51
154 
+7.1.3.  BAD Response ..............................................   52
155 
+7.1.4.  PREAUTH Response ..........................................   52
156 
+7.1.5.  BYE Response ..............................................   52
157 
+7.2.    Server Responses - Server and Mailbox Status ..............   53
158 
+7.2.1.  CAPABILITY Response .......................................   53
159 
+7.2.2.  LIST Response ..............................................  54
160 
+7.2.3.  LSUB Response .............................................   55
161 
+7.2.4   STATUS Response ...........................................   55
162 
+7.2.5.  SEARCH Response ...........................................   55
163 
+7.2.6.  FLAGS Response ............................................   56
164 
+7.3.    Server Responses - Mailbox Size ...........................   56
165 
+7.3.1.  EXISTS Response ...........................................   56
166 
+7.3.2.  RECENT Response ...........................................   57
167 
+
168 
+
169 
+
170 
+Crispin                     Standards Track                     [Page 3]
171 
+
172 
+RFC 2060                       IMAP4rev1                   December 1996
173 
+
174 
+
175 
+7.4.    Server Responses - Message Status .........................   57
176 
+7.4.1.  EXPUNGE Response ..........................................   57
177 
+7.4.2.  FETCH Response ............................................   58
178 
+7.5.    Server Responses - Command Continuation Request ...........   63
179 
+8.      Sample IMAP4rev1 connection ...............................   63
180 
+9.      Formal Syntax .............................................   64
181 
+10.     Author's Note .............................................   74
182 
+11.     Security Considerations ...................................   74
183 
+12.     Author's Address ..........................................   75
184 
+Appendices ........................................................   76
185 
+A.      References ................................................   76
186 
+B.      Changes from RFC 1730 .....................................   77
187 
+C.      Key Word Index ............................................   79
188 
+
189 
+
190 
+IMAP4rev1 Protocol Specification
191 
+
192 
+1.      How to Read This Document
193 
+
194 
+1.1.    Organization of This Document
195 
+
196 
+   This document is written from the point of view of the implementor of
197 
+   an IMAP4rev1 client or server.  Beyond the protocol overview in
198 
+   section 2, it is not optimized for someone trying to understand the
199 
+   operation of the protocol.  The material in sections 3 through 5
200 
+   provides the general context and definitions with which IMAP4rev1
201 
+   operates.
202 
+
203 
+   Sections 6, 7, and 9 describe the IMAP commands, responses, and
204 
+   syntax, respectively.  The relationships among these are such that it
205 
+   is almost impossible to understand any of them separately.  In
206 
+   particular, do not attempt to deduce command syntax from the command
207 
+   section alone; instead refer to the Formal Syntax section.
208 
+
209 
+1.2.    Conventions Used in This Document
210 
+
211 
+   In examples, "C:" and "S:" indicate lines sent by the client and
212 
+   server respectively.
213 
+
214 
+   The following terms are used in this document to signify the
215 
+   requirements of this specification.
216 
+
217 
+   1) MUST, or the adjective REQUIRED, means that the definition is
218 
+      an absolute requirement of the specification.
219 
+
220 
+   2) MUST NOT that the definition is an absolute prohibition of the
221 
+      specification.
222 
+
223 
+
224 
+
225 
+
226 
+Crispin                     Standards Track                     [Page 4]
227 
+
228 
+RFC 2060                       IMAP4rev1                   December 1996
229 
+
230 
+
231 
+   3) SHOULD means that there may exist valid reasons in particular
232 
+      circumstances to ignore a particular item, but the full
233 
+      implications MUST be understood and carefully weighed before
234 
+      choosing a different course.
235 
+
236 
+   4) SHOULD NOT means that there may exist valid reasons in
237 
+      particular circumstances when the particular behavior is
238 
+      acceptable or even useful, but the full implications SHOULD be
239 
+      understood and the case carefully weighed before implementing
240 
+      any behavior described with this label.
241 
+
242 
+   5) MAY, or the adjective OPTIONAL, means that an item is truly
243 
+      optional.  One vendor may choose to include the item because a
244 
+      particular marketplace requires it or because the vendor feels
245 
+      that it enhances the product while another vendor may omit the
246 
+      same item.  An implementation which does not include a
247 
+      particular option MUST be prepared to interoperate with another
248 
+      implementation which does include the option.
249 
+
250 
+      "Can" is used instead of "may" when referring to a possible
251 
+      circumstance or situation, as opposed to an optional facility of
252 
+      the protocol.
253 
+
254 
+      "User" is used to refer to a human user, whereas "client" refers
255 
+      to the software being run by the user.
256 
+
257 
+      "Connection" refers to the entire sequence of client/server
258 
+      interaction from the initial establishment of the network
259 
+      connection until its termination.  "Session" refers to the
260 
+      sequence of client/server interaction from the time that a mailbox
261 
+      is selected (SELECT or EXAMINE command) until the time that
262 
+      selection ends (SELECT or EXAMINE of another mailbox, CLOSE
263 
+      command, or connection termination).
264 
+
265 
+       Characters are 7-bit US-ASCII unless otherwise specified.  Other
266 
+       character sets are indicated using a "CHARSET", as described in
267 
+       [MIME-IMT] and defined in [CHARSET].  CHARSETs have important
268 
+       additional semantics in addition to defining character set; refer
269 
+       to these documents for more detail.
270 
+
271 
+2.      Protocol Overview
272 
+
273 
+2.1.    Link Level
274 
+
275 
+   The IMAP4rev1 protocol assumes a reliable data stream such as
276 
+   provided by TCP.  When TCP is used, an IMAP4rev1 server listens on
277 
+   port 143.
278 
+
279 
+
280 
+
281 
+
282 
+Crispin                     Standards Track                     [Page 5]
283 
+
284 
+RFC 2060                       IMAP4rev1                   December 1996
285 
+
286 
+
287 
+2.2.    Commands and Responses
288 
+
289 
+   An IMAP4rev1 connection consists of the establishment of a
290 
+   client/server network connection, an initial greeting from the
291 
+   server, and client/server interactions.  These client/server
292 
+   interactions consist of a client command, server data, and a server
293 
+   completion result response.
294 
+
295 
+   All interactions transmitted by client and server are in the form of
296 
+   lines; that is, strings that end with a CRLF.  The protocol receiver
297 
+   of an IMAP4rev1 client or server is either reading a line, or is
298 
+   reading a sequence of octets with a known count followed by a line.
299 
+
300 
+2.2.1.  Client Protocol Sender and Server Protocol Receiver
301 
+
302 
+   The client command begins an operation.  Each client command is
303 
+   prefixed with an identifier (typically a short alphanumeric string,
304 
+   e.g. A0001, A0002, etc.) called a "tag".  A different tag is
305 
+   generated by the client for each command.
306 
+
307 
+   There are two cases in which a line from the client does not
308 
+   represent a complete command.  In one case, a command argument is
309 
+   quoted with an octet count (see the description of literal in String
310 
+   under Data Formats); in the other case, the command arguments require
311 
+   server feedback (see the AUTHENTICATE command).  In either case, the
312 
+   server sends a command continuation request response if it is ready
313 
+   for the octets (if appropriate) and the remainder of the command.
314 
+   This response is prefixed with the token "+".
315 
+
316 
+      Note: If, instead, the server detected an error in the command, it
317 
+      sends a BAD completion response with tag matching the command (as
318 
+      described below) to reject the command and prevent the client from
319 
+      sending any more of the command.
320 
+
321 
+      It is also possible for the server to send a completion response
322 
+      for some other command (if multiple commands are in progress), or
323 
+      untagged data.  In either case, the command continuation request
324 
+      is still pending; the client takes the appropriate action for the
325 
+      response, and reads another response from the server.  In all
326 
+      cases, the client MUST send a complete command (including
327 
+      receiving all command continuation request responses and command
328 
+      continuations for the command) before initiating a new command.
329 
+
330 
+   The protocol receiver of an IMAP4rev1 server reads a command line
331 
+   from the client, parses the command and its arguments, and transmits
332 
+   server data and a server command completion result response.
333 
+
334 
+
335 
+
336 
+
337 
+
338 
+Crispin                     Standards Track                     [Page 6]
339 
+
340 
+RFC 2060                       IMAP4rev1                   December 1996
341 
+
342 
+
343 
+2.2.2.  Server Protocol Sender and Client Protocol Receiver
344 
+
345 
+   Data transmitted by the server to the client and status responses
346 
+   that do not indicate command completion are prefixed with the token
347 
+   "*", and are called untagged responses.
348 
+
349 
+   Server data MAY be sent as a result of a client command, or MAY be
350 
+   sent unilaterally by the server.  There is no syntactic difference
351 
+   between server data that resulted from a specific command and server
352 
+   data that were sent unilaterally.
353 
+
354 
+   The server completion result response indicates the success or
355 
+   failure of the operation.  It is tagged with the same tag as the
356 
+   client command which began the operation.  Thus, if more than one
357 
+   command is in progress, the tag in a server completion response
358 
+   identifies the command to which the response applies.  There are
359 
+   three possible server completion responses: OK (indicating success),
360 
+   NO (indicating failure), or BAD (indicating protocol error such as
361 
+   unrecognized command or command syntax error).
362 
+
363 
+   The protocol receiver of an IMAP4rev1 client reads a response line
364 
+   from the server.  It then takes action on the response based upon the
365 
+   first token of the response, which can be a tag, a "*", or a "+".
366 
+
367 
+   A client MUST be prepared to accept any server response at all times.
368 
+   This includes server data that was not requested.  Server data SHOULD
369 
+   be recorded, so that the client can reference its recorded copy
370 
+   rather than sending a command to the server to request the data.  In
371 
+   the case of certain server data, the data MUST be recorded.
372 
+
373 
+   This topic is discussed in greater detail in the Server Responses
374 
+   section.
375 
+
376 
+2.3.    Message Attributes
377 
+
378 
+   In addition to message text, each message has several attributes
379 
+   associated with it.  These attributes may be retrieved individually
380 
+   or in conjunction with other attributes or message texts.
381 
+
382 
+2.3.1.  Message Numbers
383 
+
384 
+   Messages in IMAP4rev1 are accessed by one of two numbers; the unique
385 
+   identifier and the message sequence number.
386 
+
387 
+2.3.1.1.        Unique Identifier (UID) Message Attribute
388 
+
389 
+   A 32-bit value assigned to each message, which when used with the
390 
+   unique identifier validity value (see below) forms a 64-bit value
391 
+
392 
+
393 
+
394 
+Crispin                     Standards Track                     [Page 7]
395 
+
396 
+RFC 2060                       IMAP4rev1                   December 1996
397 
+
398 
+
399 
+   that is permanently guaranteed not to refer to any other message in
400 
+   the mailbox.  Unique identifiers are assigned in a strictly ascending
401 
+   fashion in the mailbox; as each message is added to the mailbox it is
402 
+   assigned a higher UID than the message(s) which were added
403 
+   previously.
404 
+
405 
+   Unlike message sequence numbers, unique identifiers are not
406 
+   necessarily contiguous.  Unique identifiers also persist across
407 
+   sessions.  This permits a client to resynchronize its state from a
408 
+   previous session with the server (e.g. disconnected or offline access
409 
+   clients); this is discussed further in [IMAP-DISC].
410 
+
411 
+   Associated with every mailbox is a unique identifier validity value,
412 
+   which is sent in an UIDVALIDITY response code in an OK untagged
413 
+   response at mailbox selection time.  If unique identifiers from an
414 
+   earlier session fail to persist to this session, the unique
415 
+   identifier validity value MUST be greater than the one used in the
416 
+   earlier session.
417 
+
418 
+      Note: Unique identifiers MUST be strictly ascending in the mailbox
419 
+      at all times.  If the physical message store is re-ordered by a
420 
+      non-IMAP agent, this requires that the unique identifiers in the
421 
+      mailbox be regenerated, since the former unique identifers are no
422 
+      longer strictly ascending as a result of the re-ordering.  Another
423 
+      instance in which unique identifiers are regenerated is if the
424 
+      message store has no mechanism to store unique identifiers.
425 
+      Although this specification recognizes that this may be
426 
+      unavoidable in certain server environments, it STRONGLY ENCOURAGES
427 
+      message store implementation techniques that avoid this problem.
428 
+
429 
+      Another cause of non-persistance is if the mailbox is deleted and
430 
+      a new mailbox with the same name is created at a later date, Since
431 
+      the name is the same, a client may not know that this is a new
432 
+      mailbox unless the unique identifier validity is different.  A
433 
+      good value to use for the unique identifier validity value is a
434 
+      32-bit representation of the creation date/time of the mailbox.
435 
+      It is alright to use a constant such as 1, but only if it
436 
+      guaranteed that unique identifiers will never be reused, even in
437 
+      the case of a mailbox being deleted (or renamed) and a new mailbox
438 
+      by the same name created at some future time.
439 
+
440 
+   The unique identifier of a message MUST NOT change during the
441 
+   session, and SHOULD NOT change between sessions.  However, if it is
442 
+   not possible to preserve the unique identifier of a message in a
443 
+   subsequent session, each subsequent session MUST have a new unique
444 
+   identifier validity value that is larger than any that was used
445 
+   previously.
446 
+
447 
+
448 
+
449 
+
450 
+Crispin                     Standards Track                     [Page 8]
451 
+
452 
+RFC 2060                       IMAP4rev1                   December 1996
453 
+
454 
+
455 
+2.3.1.2.        Message Sequence Number Message Attribute
456 
+
457 
+   A relative position from 1 to the number of messages in the mailbox.
458 
+   This position MUST be ordered by ascending unique identifier.  As
459 
+   each new message is added, it is assigned a message sequence number
460 
+   that is 1 higher than the number of messages in the mailbox before
461 
+   that new message was added.
462 
+
463 
+   Message sequence numbers can be reassigned during the session.  For
464 
+   example, when a message is permanently removed (expunged) from the
465 
+   mailbox, the message sequence number for all subsequent messages is
466 
+   decremented.  Similarly, a new message can be assigned a message
467 
+   sequence number that was once held by some other message prior to an
468 
+   expunge.
469 
+
470 
+   In addition to accessing messages by relative position in the
471 
+   mailbox, message sequence numbers can be used in mathematical
472 
+   calculations.  For example, if an untagged "EXISTS 11" is received,
473 
+   and previously an untagged "8 EXISTS" was received, three new
474 
+   messages have arrived with message sequence numbers of 9, 10, and 11.
475 
+   Another example; if message 287 in a 523 message mailbox has UID
476 
+   12345, there are exactly 286 messages which have lesser UIDs and 236
477 
+   messages which have greater UIDs.
478 
+
479 
+2.3.2.  Flags Message Attribute
480 
+
481 
+   A list of zero or more named tokens associated with the message.  A
482 
+   flag is set by its addition to this list, and is cleared by its
483 
+   removal.  There are two types of flags in IMAP4rev1.  A flag of
484 
+   either type may be permanent or session-only.
485 
+
486 
+   A system flag is a flag name that is pre-defined in this
487 
+   specification.  All system flags begin with "\".  Certain system
488 
+   flags (\Deleted and \Seen) have special semantics described
489 
+   elsewhere.  The currently-defined system flags are:
490 
+
491 
+        \Seen       Message has been read
492 
+
493 
+        \Answered   Message has been answered
494 
+
495 
+        \Flagged    Message is "flagged" for urgent/special attention
496 
+
497 
+        \Deleted    Message is "deleted" for removal by later EXPUNGE
498 
+
499 
+        \Draft      Message has not completed composition (marked as a
500 
+                    draft).
501 
+
502 
+
503 
+
504 
+
505 
+
506 
+Crispin                     Standards Track                     [Page 9]
507 
+
508 
+RFC 2060                       IMAP4rev1                   December 1996
509 
+
510 
+
511 
+        \Recent     Message is "recently" arrived in this mailbox.  This
512 
+                    session is the first session to have been notified
513 
+                    about this message; subsequent sessions will not see
514 
+                    \Recent set for this message.  This flag can not be
515 
+                    altered by the client.
516 
+
517 
+                    If it is not possible to determine whether or not
518 
+                    this session is the first session to be notified
519 
+                    about a message, then that message SHOULD be
520 
+                    considered recent.
521 
+
522 
+                    If multiple connections have the same mailbox
523 
+                    selected simultaneously, it is undefined which of
524 
+                    these connections will see newly-arrives messages
525 
+                    with \Recent set and which will see it without
526 
+                    \Recent set.
527 
+
528 
+      A keyword is defined by the server implementation.  Keywords do
529 
+      not begin with "\".  Servers MAY permit the client to define new
530 
+      keywords in the mailbox (see the description of the
531 
+      PERMANENTFLAGS response code for more information).
532 
+
533 
+      A flag may be permanent or session-only on a per-flag basis.
534 
+      Permanent flags are those which the client can add or remove
535 
+      from the message flags permanently; that is, subsequent sessions
536 
+      will see any change in permanent flags.  Changes to session
537 
+      flags are valid only in that session.
538 
+
539 
+      Note: The \Recent system flag is a special case of a
540 
+      session flag.  \Recent can not be used as an argument in a
541 
+      STORE command, and thus can not be changed at all.
542 
+
543 
+2.3.3.  Internal Date Message Attribute
544 
+
545 
+   The internal date and time of the message on the server.  This is not
546 
+   the date and time in the [RFC-822] header, but rather a date and time
547 
+   which reflects when the message was received.  In the case of
548 
+   messages delivered via [SMTP], this SHOULD be the date and time of
549 
+   final delivery of the message as defined by [SMTP].  In the case of
550 
+   messages delivered by the IMAP4rev1 COPY command, this SHOULD be the
551 
+   internal date and time of the source message.  In the case of
552 
+   messages delivered by the IMAP4rev1 APPEND command, this SHOULD be
553 
+   the date and time as specified in the APPEND command description.
554 
+   All other cases are implementation defined.
555 
+
556 
+
557 
+
558 
+
559 
+
560 
+
561 
+
562 
+Crispin                     Standards Track                    [Page 10]
563 
+
564 
+RFC 2060                       IMAP4rev1                   December 1996
565 
+
566 
+
567 
+2.3.4.  [RFC-822] Size Message Attribute
568 
+
569 
+   The number of octets in the message, as expressed in [RFC-822]
570 
+   format.
571 
+
572 
+2.3.5.  Envelope Structure Message Attribute
573 
+
574 
+   A parsed representation of the [RFC-822] envelope information (not to
575 
+   be confused with an [SMTP] envelope) of the message.
576 
+
577 
+2.3.6.  Body Structure Message Attribute
578 
+
579 
+   A parsed representation of the [MIME-IMB] body structure information
580 
+   of the message.
581 
+
582 
+2.4.    Message Texts
583 
+
584 
+   In addition to being able to fetch the full [RFC-822] text of a
585 
+   message, IMAP4rev1 permits the fetching of portions of the full
586 
+   message text.  Specifically, it is possible to fetch the [RFC-822]
587 
+   message header, [RFC-822] message body, a [MIME-IMB] body part, or a
588 
+   [MIME-IMB] header.
589 
+
590 
+3.      State and Flow Diagram
591 
+
592 
+   An IMAP4rev1 server is in one of four states.  Most commands are
593 
+   valid in only certain states.  It is a protocol error for the client
594 
+   to attempt a command while the command is in an inappropriate state.
595 
+   In this case, a server will respond with a BAD or NO (depending upon
596 
+   server implementation) command completion result.
597 
+
598 
+3.1.    Non-Authenticated State
599 
+
600 
+   In non-authenticated state, the client MUST supply authentication
601 
+   credentials before most commands will be permitted.  This state is
602 
+   entered when a connection starts unless the connection has been pre-
603 
+   authenticated.
604 
+
605 
+3.2.    Authenticated State
606 
+
607 
+   In authenticated state, the client is authenticated and MUST select a
608 
+   mailbox to access before commands that affect messages will be
609 
+   permitted.  This state is entered when a pre-authenticated connection
610 
+   starts, when acceptable authentication credentials have been
611 
+   provided, or after an error in selecting a mailbox.
612 
+
613 
+
614 
+
615 
+
616 
+
617 
+
618 
+Crispin                     Standards Track                    [Page 11]
619 
+
620 
+RFC 2060                       IMAP4rev1                   December 1996
621 
+
622 
+
623 
+3.3.    Selected State
624 
+
625 
+   In selected state, a mailbox has been selected to access.  This state
626 
+   is entered when a mailbox has been successfully selected.
627 
+
628 
+3.4.    Logout State
629 
+
630 
+   In logout state, the connection is being terminated, and the server
631 
+   will close the connection.  This state can be entered as a result of
632 
+   a client request or by unilateral server decision.
633 
+
634 
+            +--------------------------------------+
635 
+            |initial connection and server greeting|
636 
+            +--------------------------------------+
637 
+                      || (1)       || (2)        || (3)
638 
+                      VV           ||            ||
639 
+            +-----------------+    ||            ||
640 
+            |non-authenticated|    ||            ||
641 
+            +-----------------+    ||            ||
642 
+             || (7)   || (4)       ||            ||
643 
+             ||       VV           VV            ||
644 
+             ||     +----------------+           ||
645 
+             ||     | authenticated  |<=++       ||
646 
+             ||     +----------------+  ||       ||
647 
+             ||       || (7)   || (5)   || (6)   ||
648 
+             ||       ||       VV       ||       ||
649 
+             ||       ||    +--------+  ||       ||
650 
+             ||       ||    |selected|==++       ||
651 
+             ||       ||    +--------+           ||
652 
+             ||       ||       || (7)            ||
653 
+             VV       VV       VV                VV
654 
+            +--------------------------------------+
655 
+            |     logout and close connection      |
656 
+            +--------------------------------------+
657 
+
658 
+         (1) connection without pre-authentication (OK greeting)
659 
+         (2) pre-authenticated connection (PREAUTH greeting)
660 
+         (3) rejected connection (BYE greeting)
661 
+         (4) successful LOGIN or AUTHENTICATE command
662 
+         (5) successful SELECT or EXAMINE command
663 
+         (6) CLOSE command, or failed SELECT or EXAMINE command
664 
+         (7) LOGOUT command, server shutdown, or connection closed
665 
+
666 
+4.      Data Formats
667 
+
668 
+   IMAP4rev1 uses textual commands and responses.  Data in IMAP4rev1 can
669 
+   be in one of several forms: atom, number, string, parenthesized list,
670 
+   or NIL.
671 
+
672 
+
673 
+
674 
+Crispin                     Standards Track                    [Page 12]
675 
+
676 
+RFC 2060                       IMAP4rev1                   December 1996
677 
+
678 
+
679 
+4.1.    Atom
680 
+
681 
+   An atom consists of one or more non-special characters.
682 
+
683 
+4.2.    Number
684 
+
685 
+   A number consists of one or more digit characters, and represents a
686 
+   numeric value.
687 
+
688 
+4.3.    String
689 
+
690 
+   A string is in one of two forms: literal and quoted string.  The
691 
+   literal form is the general form of string.  The quoted string form
692 
+   is an alternative that avoids the overhead of processing a literal at
693 
+   the cost of limitations of characters that can be used in a quoted
694 
+   string.
695 
+
696 
+   A literal is a sequence of zero or more octets (including CR and LF),
697 
+   prefix-quoted with an octet count in the form of an open brace ("{"),
698 
+   the number of octets, close brace ("}"), and CRLF.  In the case of
699 
+   literals transmitted from server to client, the CRLF is immediately
700 
+   followed by the octet data.  In the case of literals transmitted from
701 
+   client to server, the client MUST wait to receive a command
702 
+   continuation request (described later in this document) before
703 
+   sending the octet data (and the remainder of the command).
704 
+
705 
+   A quoted string is a sequence of zero or more 7-bit characters,
706 
+   excluding CR and LF, with double quote (<">) characters at each end.
707 
+
708 
+   The empty string is represented as either "" (a quoted string with
709 
+   zero characters between double quotes) or as {0} followed by CRLF (a
710 
+   literal with an octet count of 0).
711 
+
712 
+      Note: Even if the octet count is 0, a client transmitting a
713 
+      literal MUST wait to receive a command continuation request.
714 
+
715 
+4.3.1.  8-bit and Binary Strings
716 
+
717 
+   8-bit textual and binary mail is supported through the use of a
718 
+   [MIME-IMB] content transfer encoding.  IMAP4rev1 implementations MAY
719 
+   transmit 8-bit or multi-octet characters in literals, but SHOULD do
720 
+   so only when the [CHARSET] is identified.
721 
+
722 
+
723 
+
724 
+
725 
+
726 
+
727 
+
728 
+
729 
+
730 
+Crispin                     Standards Track                    [Page 13]
731 
+
732 
+RFC 2060                       IMAP4rev1                   December 1996
733 
+
734 
+
735 
+   Although a BINARY body encoding is defined, unencoded binary strings
736 
+   are not permitted.  A "binary string" is any string with NUL
737 
+   characters.  Implementations MUST encode binary data into a textual
738 
+   form such as BASE64 before transmitting the data.  A string with an
739 
+   excessive amount of CTL characters MAY also be considered to be
740 
+   binary.
741 
+
742 
+4.4.    Parenthesized List
743 
+
744 
+   Data structures are represented as a "parenthesized list"; a sequence
745 
+   of data items, delimited by space, and bounded at each end by
746 
+   parentheses.  A parenthesized list can contain other parenthesized
747 
+   lists, using multiple levels of parentheses to indicate nesting.
748 
+
749 
+   The empty list is represented as () -- a parenthesized list with no
750 
+   members.
751 
+
752 
+4.5.    NIL
753 
+
754 
+   The special atom "NIL" represents the non-existence of a particular
755 
+   data item that is represented as a string or parenthesized list, as
756 
+   distinct from the empty string "" or the empty parenthesized list ().
757 
+
758 
+5.      Operational Considerations
759 
+
760 
+5.1.    Mailbox Naming
761 
+
762 
+   The interpretation of mailbox names is implementation-dependent.
763 
+   However, the case-insensitive mailbox name INBOX is a special name
764 
+   reserved to mean "the primary mailbox for this user on this server".
765 
+
766 
+5.1.1.  Mailbox Hierarchy Naming
767 
+
768 
+   If it is desired to export hierarchical mailbox names, mailbox names
769 
+   MUST be left-to-right hierarchical using a single character to
770 
+   separate levels of hierarchy.  The same hierarchy separator character
771 
+   is used for all levels of hierarchy within a single name.
772 
+
773 
+5.1.2.  Mailbox Namespace Naming Convention
774 
+
775 
+   By convention, the first hierarchical element of any mailbox name
776 
+   which begins with "#" identifies the "namespace" of the remainder of
777 
+   the name.  This makes it possible to disambiguate between different
778 
+   types of mailbox stores, each of which have their own namespaces.
779 
+
780 
+
781 
+
782 
+
783 
+
784 
+
785 
+
786 
+Crispin                     Standards Track                    [Page 14]
787 
+
788 
+RFC 2060                       IMAP4rev1                   December 1996
789 
+
790 
+
791 
+      For example, implementations which offer access to USENET
792 
+      newsgroups MAY use the "#news" namespace to partition the USENET
793 
+      newsgroup namespace from that of other mailboxes.  Thus, the
794 
+      comp.mail.misc newsgroup would have an mailbox name of
795 
+      "#news.comp.mail.misc", and the name "comp.mail.misc" could refer
796 
+      to a different object (e.g. a user's private mailbox).
797 
+
798 
+5.1.3.  Mailbox International Naming Convention
799 
+
800 
+   By convention, international mailbox names are specified using a
801 
+   modified version of the UTF-7 encoding described in [UTF-7].  The
802 
+   purpose of these modifications is to correct the following problems
803 
+   with UTF-7:
804 
+
805 
+      1) UTF-7 uses the "+" character for shifting; this conflicts with
806 
+         the common use of "+" in mailbox names, in particular USENET
807 
+         newsgroup names.
808 
+
809 
+      2) UTF-7's encoding is BASE64 which uses the "/" character; this
810 
+         conflicts with the use of "/" as a popular hierarchy delimiter.
811 
+
812 
+      3) UTF-7 prohibits the unencoded usage of "\"; this conflicts with
813 
+         the use of "\" as a popular hierarchy delimiter.
814 
+
815 
+      4) UTF-7 prohibits the unencoded usage of "~"; this conflicts with
816 
+         the use of "~" in some servers as a home directory indicator.
817 
+
818 
+      5) UTF-7 permits multiple alternate forms to represent the same
819 
+         string; in particular, printable US-ASCII chararacters can be
820 
+         represented in encoded form.
821 
+
822 
+   In modified UTF-7, printable US-ASCII characters except for "&"
823 
+   represent themselves; that is, characters with octet values 0x20-0x25
824 
+   and 0x27-0x7e.  The character "&" (0x26) is represented by the two-
825 
+   octet sequence "&-".
826 
+
827 
+   All other characters (octet values 0x00-0x1f, 0x7f-0xff, and all
828 
+   Unicode 16-bit octets) are represented in modified BASE64, with a
829 
+   further modification from [UTF-7] that "," is used instead of "/".
830 
+   Modified BASE64 MUST NOT be used to represent any printing US-ASCII
831 
+   character which can represent itself.
832 
+
833 
+   "&" is used to shift to modified BASE64 and "-" to shift back to US-
834 
+   ASCII.  All names start in US-ASCII, and MUST end in US-ASCII (that
835 
+   is, a name that ends with a Unicode 16-bit octet MUST end with a "-
836 
+   ").
837 
+
838 
+
839 
+
840 
+
841 
+
842 
+Crispin                     Standards Track                    [Page 15]
843 
+
844 
+RFC 2060                       IMAP4rev1                   December 1996
845 
+
846 
+
847 
+      For example, here is a mailbox name which mixes English, Japanese,
848 
+      and Chinese text: ~peter/mail/&ZeVnLIqe-/&U,BTFw-
849 
+
850 
+5.2.    Mailbox Size and Message Status Updates
851 
+
852 
+   At any time, a server can send data that the client did not request.
853 
+   Sometimes, such behavior is REQUIRED.  For example, agents other than
854 
+   the server MAY add messages to the mailbox (e.g. new mail delivery),
855 
+   change the flags of message in the mailbox (e.g. simultaneous access
856 
+   to the same mailbox by multiple agents), or even remove messages from
857 
+   the mailbox.  A server MUST send mailbox size updates automatically
858 
+   if a mailbox size change is observed during the processing of a
859 
+   command.  A server SHOULD send message flag updates automatically,
860 
+   without requiring the client to request such updates explicitly.
861 
+   Special rules exist for server notification of a client about the
862 
+   removal of messages to prevent synchronization errors; see the
863 
+   description of the EXPUNGE response for more detail.
864 
+
865 
+   Regardless of what implementation decisions a client makes on
866 
+   remembering data from the server, a client implementation MUST record
867 
+   mailbox size updates.  It MUST NOT assume that any command after
868 
+   initial mailbox selection will return the size of the mailbox.
869 
+
870 
+5.3.    Response when no Command in Progress
871 
+
872 
+   Server implementations are permitted to send an untagged response
873 
+   (except for EXPUNGE) while there is no command in progress.  Server
874 
+   implementations that send such responses MUST deal with flow control
875 
+   considerations.  Specifically, they MUST either (1) verify that the
876 
+   size of the data does not exceed the underlying transport's available
877 
+   window size, or (2) use non-blocking writes.
878 
+
879 
+5.4.    Autologout Timer
880 
+
881 
+   If a server has an inactivity autologout timer, that timer MUST be of
882 
+   at least 30 minutes' duration.  The receipt of ANY command from the
883 
+   client during that interval SHOULD suffice to reset the autologout
884 
+   timer.
885 
+
886 
+
887 
+
888 
+
889 
+
890 
+
891 
+
892 
+
893 
+
894 
+
895 
+
896 
+
897 
+
898 
+Crispin                     Standards Track                    [Page 16]
899 
+
900 
+RFC 2060                       IMAP4rev1                   December 1996
901 
+
902 
+
903 
+5.5.    Multiple Commands in Progress
904 
+
905 
+   The client MAY send another command without waiting for the
906 
+   completion result response of a command, subject to ambiguity rules
907 
+   (see below) and flow control constraints on the underlying data
908 
+   stream.  Similarly, a server MAY begin processing another command
909 
+   before processing the current command to completion, subject to
910 
+   ambiguity rules.  However, any command continuation request responses
911 
+   and command continuations MUST be negotiated before any subsequent
912 
+   command is initiated.
913 
+
914 
+   The exception is if an ambiguity would result because of a command
915 
+   that would affect the results of other commands.  Clients MUST NOT
916 
+   send multiple commands without waiting if an ambiguity would result.
917 
+   If the server detects a possible ambiguity, it MUST execute commands
918 
+   to completion in the order given by the client.
919 
+
920 
+   The most obvious example of ambiguity is when a command would affect
921 
+   the results of another command; for example, a FETCH of a message's
922 
+   flags and a STORE of that same message's flags.
923 
+
924 
+   A non-obvious ambiguity occurs with commands that permit an untagged
925 
+   EXPUNGE response (commands other than FETCH, STORE, and SEARCH),
926 
+   since an untagged EXPUNGE response can invalidate sequence numbers in
927 
+   a subsequent command.  This is not a problem for FETCH, STORE, or
928 
+   SEARCH commands because servers are prohibited from sending EXPUNGE
929 
+   responses while any of those commands are in progress.  Therefore, if
930 
+   the client sends any command other than FETCH, STORE, or SEARCH, it
931 
+   MUST wait for a response before sending a command with message
932 
+   sequence numbers.
933 
+
934 
+   For example, the following non-waiting command sequences are invalid:
935 
+
936 
+      FETCH + NOOP + STORE
937 
+      STORE + COPY + FETCH
938 
+      COPY + COPY
939 
+      CHECK + FETCH
940 
+
941 
+   The following are examples of valid non-waiting command sequences:
942 
+
943 
+      FETCH + STORE + SEARCH + CHECK
944 
+      STORE + COPY + EXPUNGE
945 
+
946 
+6.      Client Commands
947 
+
948 
+   IMAP4rev1 commands are described in this section.  Commands are
949 
+   organized by the state in which the command is permitted.  Commands
950 
+   which are permitted in multiple states are listed in the minimum
951 
+
952 
+
953 
+
954 
+Crispin                     Standards Track                    [Page 17]
955 
+
956 
+RFC 2060                       IMAP4rev1                   December 1996
957 
+
958 
+
959 
+   permitted state (for example, commands valid in authenticated and
960 
+   selected state are listed in the authenticated state commands).
961 
+
962 
+   Command arguments, identified by "Arguments:" in the command
963 
+   descriptions below, are described by function, not by syntax.  The
964 
+   precise syntax of command arguments is described in the Formal Syntax
965 
+   section.
966 
+
967 
+   Some commands cause specific server responses to be returned; these
968 
+   are identified by "Responses:" in the command descriptions below.
969 
+   See the response descriptions in the Responses section for
970 
+   information on these responses, and the Formal Syntax section for the
971 
+   precise syntax of these responses.  It is possible for server data to
972 
+   be transmitted as a result of any command; thus, commands that do not
973 
+   specifically require server data specify "no specific responses for
974 
+   this command" instead of "none".
975 
+
976 
+   The "Result:" in the command description refers to the possible
977 
+   tagged status responses to a command, and any special interpretation
978 
+   of these status responses.
979 
+
980 
+6.1.    Client Commands - Any State
981 
+
982 
+   The following commands are valid in any state: CAPABILITY, NOOP, and
983 
+   LOGOUT.
984 
+
985 
+6.1.1.  CAPABILITY Command
986 
+
987 
+   Arguments:  none
988 
+
989 
+   Responses:  REQUIRED untagged response: CAPABILITY
990 
+
991 
+   Result:     OK - capability completed
992 
+               BAD - command unknown or arguments invalid
993 
+
994 
+      The CAPABILITY command requests a listing of capabilities that the
995 
+      server supports.  The server MUST send a single untagged
996 
+      CAPABILITY response with "IMAP4rev1" as one of the listed
997 
+      capabilities before the (tagged) OK response.  This listing of
998 
+      capabilities is not dependent upon connection state or user.  It
999 
+      is therefore not necessary to issue a CAPABILITY command more than
1000 
+      once in a connection.
1001 
+
1002 
+
1003 
+
1004 
+
1005 
+
1006 
+
1007 
+
1008 
+
1009 
+
1010 
+Crispin                     Standards Track                    [Page 18]
1011 
+
1012 
+RFC 2060                       IMAP4rev1                   December 1996
1013 
+
1014 
+
1015 
+      A capability name which begins with "AUTH=" indicates that the
1016 
+      server supports that particular authentication mechanism.  All
1017 
+      such names are, by definition, part of this specification.  For
1018 
+      example, the authorization capability for an experimental
1019 
+      "blurdybloop" authenticator would be "AUTH=XBLURDYBLOOP" and not
1020 
+      "XAUTH=BLURDYBLOOP" or "XAUTH=XBLURDYBLOOP".
1021 
+
1022 
+      Other capability names refer to extensions, revisions, or
1023 
+      amendments to this specification.  See the documentation of the
1024 
+      CAPABILITY response for additional information.  No capabilities,
1025 
+      beyond the base IMAP4rev1 set defined in this specification, are
1026 
+      enabled without explicit client action to invoke the capability.
1027 
+
1028 
+      See the section entitled "Client Commands -
1029 
+      Experimental/Expansion" for information about the form of site or
1030 
+      implementation-specific capabilities.
1031 
+
1032 
+   Example:    C: abcd CAPABILITY
1033 
+               S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4
1034 
+               S: abcd OK CAPABILITY completed
1035 
+
1036 
+6.1.2.  NOOP Command
1037 
+
1038 
+   Arguments:  none
1039 
+
1040 
+   Responses:  no specific responses for this command (but see below)
1041 
+
1042 
+   Result:     OK - noop completed
1043 
+               BAD - command unknown or arguments invalid
1044 
+
1045 
+      The NOOP command always succeeds.  It does nothing.
1046 
+
1047 
+      Since any command can return a status update as untagged data, the
1048 
+      NOOP command can be used as a periodic poll for new messages or
1049 
+      message status updates during a period of inactivity.  The NOOP
1050 
+      command can also be used to reset any inactivity autologout timer
1051 
+      on the server.
1052 
+
1053 
+   Example:    C: a002 NOOP
1054 
+               S: a002 OK NOOP completed
1055 
+                  . . .
1056 
+               C: a047 NOOP
1057 
+               S: * 22 EXPUNGE
1058 
+               S: * 23 EXISTS
1059 
+               S: * 3 RECENT
1060 
+               S: * 14 FETCH (FLAGS (\Seen \Deleted))
1061 
+               S: a047 OK NOOP completed
1062 
+
1063 
+
1064 
+
1065 
+
1066 
+Crispin                     Standards Track                    [Page 19]
1067 
+
1068 
+RFC 2060                       IMAP4rev1                   December 1996
1069 
+
1070 
+
1071 
+6.1.3.  LOGOUT Command
1072 
+
1073 
+   Arguments:  none
1074 
+
1075 
+   Responses:  REQUIRED untagged response: BYE
1076 
+
1077 
+   Result:     OK - logout completed
1078 
+               BAD - command unknown or arguments invalid
1079 
+
1080 
+      The LOGOUT command informs the server that the client is done with
1081 
+      the connection.  The server MUST send a BYE untagged response
1082 
+      before the (tagged) OK response, and then close the network
1083 
+      connection.
1084 
+
1085 
+   Example:    C: A023 LOGOUT
1086 
+               S: * BYE IMAP4rev1 Server logging out
1087 
+               S: A023 OK LOGOUT completed
1088 
+               (Server and client then close the connection)
1089 
+
1090 
+6.2.    Client Commands - Non-Authenticated State
1091 
+
1092 
+   In non-authenticated state, the AUTHENTICATE or LOGIN command
1093 
+   establishes authentication and enter authenticated state.  The
1094 
+   AUTHENTICATE command provides a general mechanism for a variety of
1095 
+   authentication techniques, whereas the LOGIN command uses the
1096 
+   traditional user name and plaintext password pair.
1097 
+
1098 
+   Server implementations MAY allow non-authenticated access to certain
1099 
+   mailboxes.  The convention is to use a LOGIN command with the userid
1100 
+   "anonymous".  A password is REQUIRED.  It is implementation-dependent
1101 
+   what requirements, if any, are placed on the password and what access
1102 
+   restrictions are placed on anonymous users.
1103 
+
1104 
+   Once authenticated (including as anonymous), it is not possible to
1105 
+   re-enter non-authenticated state.
1106 
+
1107 
+   In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
1108 
+   the following commands are valid in non-authenticated state:
1109 
+   AUTHENTICATE and LOGIN.
1110 
+
1111 
+
1112 
+
1113 
+
1114 
+
1115 
+
1116 
+
1117 
+
1118 
+
1119 
+
1120 
+
1121 
+
1122 
+Crispin                     Standards Track                    [Page 20]
1123 
+
1124 
+RFC 2060                       IMAP4rev1                   December 1996
1125 
+
1126 
+
1127 
+6.2.1.  AUTHENTICATE Command
1128 
+
1129 
+   Arguments:  authentication mechanism name
1130 
+
1131 
+   Responses:  continuation data can be requested
1132 
+
1133 
+   Result:     OK - authenticate completed, now in authenticated state
1134 
+               NO - authenticate failure: unsupported authentication
1135 
+                    mechanism, credentials rejected
1136 
+              BAD - command unknown or arguments invalid,
1137 
+                    authentication exchange cancelled
1138 
+
1139 
+      The AUTHENTICATE command indicates an authentication mechanism,
1140 
+      such as described in [IMAP-AUTH], to the server.  If the server
1141 
+      supports the requested authentication mechanism, it performs an
1142 
+      authentication protocol exchange to authenticate and identify the
1143 
+      client.  It MAY also negotiate an OPTIONAL protection mechanism
1144 
+      for subsequent protocol interactions.  If the requested
1145 
+      authentication mechanism is not supported, the server SHOULD
1146 
+      reject the AUTHENTICATE command by sending a tagged NO response.
1147 
+
1148 
+      The authentication protocol exchange consists of a series of
1149 
+      server challenges and client answers that are specific to the
1150 
+      authentication mechanism.  A server challenge consists of a
1151 
+      command continuation request response with the "+" token followed
1152 
+      by a BASE64 encoded string.  The client answer consists of a line
1153 
+      consisting of a BASE64 encoded string.  If the client wishes to
1154 
+      cancel an authentication exchange, it issues a line with a single
1155 
+      "*".  If the server receives such an answer, it MUST reject the
1156 
+      AUTHENTICATE command by sending a tagged BAD response.
1157 
+
1158 
+      A protection mechanism provides integrity and privacy protection
1159 
+      to the connection.  If a protection mechanism is negotiated, it is
1160 
+      applied to all subsequent data sent over the connection.  The
1161 
+      protection mechanism takes effect immediately following the CRLF
1162 
+      that concludes the authentication exchange for the client, and the
1163 
+      CRLF of the tagged OK response for the server.  Once the
1164 
+      protection mechanism is in effect, the stream of command and
1165 
+      response octets is processed into buffers of ciphertext.  Each
1166 
+      buffer is transferred over the connection as a stream of octets
1167 
+      prepended with a four octet field in network byte order that
1168 
+      represents the length of the following data.  The maximum
1169 
+      ciphertext buffer length is defined by the protection mechanism.
1170 
+
1171 
+      Authentication mechanisms are OPTIONAL.  Protection mechanisms are
1172 
+      also OPTIONAL; an authentication mechanism MAY be implemented
1173 
+      without any protection mechanism.  If an AUTHENTICATE command
1174 
+      fails with a NO response, the client MAY try another
1175 
+
1176 
+
1177 
+
1178 
+Crispin                     Standards Track                    [Page 21]
1179 
+
1180 
+RFC 2060                       IMAP4rev1                   December 1996
1181 
+
1182 
+
1183 
+      authentication mechanism by issuing another AUTHENTICATE command,
1184 
+      or MAY attempt to authenticate by using the LOGIN command.  In
1185 
+      other words, the client MAY request authentication types in
1186 
+      decreasing order of preference, with the LOGIN command as a last
1187 
+      resort.
1188 
+
1189 
+   Example:    S: * OK KerberosV4 IMAP4rev1 Server
1190 
+               C: A001 AUTHENTICATE KERBEROS_V4
1191 
+               S: + AmFYig==
1192 
+               C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
1193 
+                  +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
1194 
+                  WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
1195 
+               S: + or//EoAADZI=
1196 
+               C: DiAF5A4gA+oOIALuBkAAmw==
1197 
+               S: A001 OK Kerberos V4 authentication successful
1198 
+
1199 
+      Note: the line breaks in the first client answer are for editorial
1200 
+      clarity and are not in real authenticators.
1201 
+
1202 
+6.2.2.  LOGIN Command
1203 
+
1204 
+   Arguments:  user name
1205 
+               password
1206 
+
1207 
+   Responses:  no specific responses for this command
1208 
+
1209 
+   Result:     OK - login completed, now in authenticated state
1210 
+               NO - login failure: user name or password rejected
1211 
+               BAD - command unknown or arguments invalid
1212 
+
1213 
+      The LOGIN command identifies the client to the server and carries
1214 
+      the plaintext password authenticating this user.
1215 
+
1216 
+   Example:    C: a001 LOGIN SMITH SESAME
1217 
+               S: a001 OK LOGIN completed
1218 
+
1219 
+6.3.    Client Commands - Authenticated State
1220 
+
1221 
+   In authenticated state, commands that manipulate mailboxes as atomic
1222 
+   entities are permitted.  Of these commands, the SELECT and EXAMINE
1223 
+   commands will select a mailbox for access and enter selected state.
1224 
+
1225 
+   In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
1226 
+   the following commands are valid in authenticated state: SELECT,
1227 
+   EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB,
1228 
+   STATUS, and APPEND.
1229 
+
1230 
+
1231 
+
1232 
+
1233 
+
1234 
+Crispin                     Standards Track                    [Page 22]
1235 
+
1236 
+RFC 2060                       IMAP4rev1                   December 1996
1237 
+
1238 
+
1239 
+6.3.1.  SELECT Command
1240 
+
1241 
+   Arguments:  mailbox name
1242 
+
1243 
+   Responses:  REQUIRED untagged responses: FLAGS, EXISTS, RECENT
1244 
+               OPTIONAL OK untagged responses: UNSEEN, PERMANENTFLAGS
1245 
+
1246 
+   Result:     OK - select completed, now in selected state
1247 
+               NO - select failure, now in authenticated state: no
1248 
+                    such mailbox, can't access mailbox
1249 
+               BAD - command unknown or arguments invalid
1250 
+
1251 
+   The SELECT command selects a mailbox so that messages in the
1252 
+   mailbox can be accessed.  Before returning an OK to the client,
1253 
+   the server MUST send the following untagged data to the client:
1254 
+
1255 
+      FLAGS       Defined flags in the mailbox.  See the description
1256 
+                  of the FLAGS response for more detail.
1257 
+
1258 
+      <n> EXISTS  The number of messages in the mailbox.  See the
1259 
+                  description of the EXISTS response for more detail.
1260 
+
1261 
+      <n> RECENT  The number of messages with the \Recent flag set.
1262 
+                  See the description of the RECENT response for more
1263 
+                  detail.
1264 
+
1265 
+      OK [UIDVALIDITY <n>]
1266 
+                  The unique identifier validity value.  See the
1267 
+                  description of the UID command for more detail.
1268 
+
1269 
+   to define the initial state of the mailbox at the client.
1270 
+
1271 
+   The server SHOULD also send an UNSEEN response code in an OK
1272 
+   untagged response, indicating the message sequence number of the
1273 
+   first unseen message in the mailbox.
1274 
+
1275 
+   If the client can not change the permanent state of one or more of
1276 
+   the flags listed in the FLAGS untagged response, the server SHOULD
1277 
+   send a PERMANENTFLAGS response code in an OK untagged response,
1278 
+   listing the flags that the client can change permanently.
1279 
+
1280 
+   Only one mailbox can be selected at a time in a connection;
1281 
+   simultaneous access to multiple mailboxes requires multiple
1282 
+   connections.  The SELECT command automatically deselects any
1283 
+   currently selected mailbox before attempting the new selection.
1284 
+   Consequently, if a mailbox is selected and a SELECT command that
1285 
+   fails is attempted, no mailbox is selected.
1286 
+
1287 
+
1288 
+
1289 
+
1290 
+Crispin                     Standards Track                    [Page 23]
1291 
+
1292 
+RFC 2060                       IMAP4rev1                   December 1996
1293 
+
1294 
+
1295 
+   If the client is permitted to modify the mailbox, the server
1296 
+   SHOULD prefix the text of the tagged OK response with the
1297 
+         "[READ-WRITE]" response code.
1298 
+
1299 
+      If the client is not permitted to modify the mailbox but is
1300 
+      permitted read access, the mailbox is selected as read-only, and
1301 
+      the server MUST prefix the text of the tagged OK response to
1302 
+      SELECT with the "[READ-ONLY]" response code.  Read-only access
1303 
+      through SELECT differs from the EXAMINE command in that certain
1304 
+      read-only mailboxes MAY permit the change of permanent state on a
1305 
+      per-user (as opposed to global) basis.  Netnews messages marked in
1306 
+      a server-based .newsrc file are an example of such per-user
1307 
+      permanent state that can be modified with read-only mailboxes.
1308 
+
1309 
+   Example:    C: A142 SELECT INBOX
1310 
+               S: * 172 EXISTS
1311 
+               S: * 1 RECENT
1312 
+               S: * OK [UNSEEN 12] Message 12 is first unseen
1313 
+               S: * OK [UIDVALIDITY 3857529045] UIDs valid
1314 
+               S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
1315 
+               S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
1316 
+               S: A142 OK [READ-WRITE] SELECT completed
1317 
+
1318 
+6.3.2.  EXAMINE Command
1319 
+
1320 
+   Arguments:  mailbox name
1321 
+
1322 
+   Responses:  REQUIRED untagged responses: FLAGS, EXISTS, RECENT
1323 
+               OPTIONAL OK untagged responses: UNSEEN, PERMANENTFLAGS
1324 
+
1325 
+   Result:     OK - examine completed, now in selected state
1326 
+               NO - examine failure, now in authenticated state: no
1327 
+                    such mailbox, can't access mailbox
1328 
+               BAD - command unknown or arguments invalid
1329 
+
1330 
+      The EXAMINE command is identical to SELECT and returns the same
1331 
+      output; however, the selected mailbox is identified as read-only.
1332 
+      No changes to the permanent state of the mailbox, including
1333 
+      per-user state, are permitted.
1334 
+
1335 
+
1336 
+
1337 
+
1338 
+
1339 
+
1340 
+
1341 
+
1342 
+
1343 
+
1344 
+
1345 
+
1346 
+Crispin                     Standards Track                    [Page 24]
1347 
+
1348 
+RFC 2060                       IMAP4rev1                   December 1996
1349 
+
1350 
+
1351 
+      The text of the tagged OK response to the EXAMINE command MUST
1352 
+      begin with the "[READ-ONLY]" response code.
1353 
+
1354 
+   Example:    C: A932 EXAMINE blurdybloop
1355 
+               S: * 17 EXISTS
1356 
+               S: * 2 RECENT
1357 
+               S: * OK [UNSEEN 8] Message 8 is first unseen
1358 
+               S: * OK [UIDVALIDITY 3857529045] UIDs valid
1359 
+               S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
1360 
+               S: * OK [PERMANENTFLAGS ()] No permanent flags permitted
1361 
+               S: A932 OK [READ-ONLY] EXAMINE completed
1362 
+
1363 
+6.3.3.  CREATE Command
1364 
+
1365 
+   Arguments:  mailbox name
1366 
+
1367 
+   Responses:  no specific responses for this command
1368 
+
1369 
+   Result:     OK - create completed
1370 
+               NO - create failure: can't create mailbox with that name
1371 
+               BAD - command unknown or arguments invalid
1372 
+
1373 
+      The CREATE command creates a mailbox with the given name.  An OK
1374 
+      response is returned only if a new mailbox with that name has been
1375 
+      created.  It is an error to attempt to create INBOX or a mailbox
1376 
+      with a name that refers to an extant mailbox.  Any error in
1377 
+      creation will return a tagged NO response.
1378 
+
1379 
+      If the mailbox name is suffixed with the server's hierarchy
1380 
+      separator character (as returned from the server by a LIST
1381 
+      command), this is a declaration that the client intends to create
1382 
+      mailbox names under this name in the hierarchy.  Server
1383 
+      implementations that do not require this declaration MUST ignore
1384 
+      it.
1385 
+
1386 
+      If the server's hierarchy separator character appears elsewhere in
1387 
+      the name, the server SHOULD create any superior hierarchical names
1388 
+      that are needed for the CREATE command to complete successfully.
1389 
+      In other words, an attempt to create "foo/bar/zap" on a server in
1390 
+      which "/" is the hierarchy separator character SHOULD create foo/
1391 
+      and foo/bar/ if they do not already exist.
1392 
+
1393 
+      If a new mailbox is created with the same name as a mailbox which
1394 
+      was deleted, its unique identifiers MUST be greater than any
1395 
+      unique identifiers used in the previous incarnation of the mailbox
1396 
+      UNLESS the new incarnation has a different unique identifier
1397 
+      validity value.  See the description of the UID command for more
1398 
+      detail.
1399 
+
1400 
+
1401 
+
1402 
+Crispin                     Standards Track                    [Page 25]
1403 
+
1404 
+RFC 2060                       IMAP4rev1                   December 1996
1405 
+
1406 
+
1407 
+   Example:    C: A003 CREATE owatagusiam/
1408 
+               S: A003 OK CREATE completed
1409 
+               C: A004 CREATE owatagusiam/blurdybloop
1410 
+               S: A004 OK CREATE completed
1411 
+
1412 
+      Note: the interpretation of this example depends on whether "/"
1413 
+      was returned as the hierarchy separator from LIST.  If "/" is the
1414 
+      hierarchy separator, a new level of hierarchy named "owatagusiam"
1415 
+      with a member called "blurdybloop" is created.  Otherwise, two
1416 
+      mailboxes at the same hierarchy level are created.
1417 
+
1418 
+6.3.4.  DELETE Command
1419 
+
1420 
+   Arguments:  mailbox name
1421 
+
1422 
+   Responses:  no specific responses for this command
1423 
+
1424 
+   Result:     OK - delete completed
1425 
+               NO - delete failure: can't delete mailbox with that name
1426 
+               BAD - command unknown or arguments invalid
1427 
+
1428 
+      The DELETE command permanently removes the mailbox with the given
1429 
+      name.  A tagged OK response is returned only if the mailbox has
1430 
+      been deleted.  It is an error to attempt to delete INBOX or a
1431 
+      mailbox name that does not exist.
1432 
+
1433 
+      The DELETE command MUST NOT remove inferior hierarchical names.
1434 
+      For example, if a mailbox "foo" has an inferior "foo.bar"
1435 
+      (assuming "." is the hierarchy delimiter character), removing
1436 
+      "foo" MUST NOT remove "foo.bar".  It is an error to attempt to
1437 
+      delete a name that has inferior hierarchical names and also has
1438 
+      the \Noselect mailbox name attribute (see the description of the
1439 
+      LIST response for more details).
1440 
+
1441 
+      It is permitted to delete a name that has inferior hierarchical
1442 
+      names and does not have the \Noselect mailbox name attribute.  In
1443 
+      this case, all messages in that mailbox are removed, and the name
1444 
+      will acquire the \Noselect mailbox name attribute.
1445 
+
1446 
+      The value of the highest-used unique identifier of the deleted
1447 
+      mailbox MUST be preserved so that a new mailbox created with the
1448 
+      same name will not reuse the identifiers of the former
1449 
+      incarnation, UNLESS the new incarnation has a different unique
1450 
+      identifier validity value.  See the description of the UID command
1451 
+      for more detail.
1452 
+
1453 
+
1454 
+
1455 
+
1456 
+
1457 
+
1458 
+Crispin                     Standards Track                    [Page 26]
1459 
+
1460 
+RFC 2060                       IMAP4rev1                   December 1996
1461 
+
1462 
+
1463 
+   Examples:   C: A682 LIST "" *
1464 
+               S: * LIST () "/" blurdybloop
1465 
+               S: * LIST (\Noselect) "/" foo
1466 
+               S: * LIST () "/" foo/bar
1467 
+               S: A682 OK LIST completed
1468 
+               C: A683 DELETE blurdybloop
1469 
+               S: A683 OK DELETE completed
1470 
+               C: A684 DELETE foo
1471 
+               S: A684 NO Name "foo" has inferior hierarchical names
1472 
+               C: A685 DELETE foo/bar
1473 
+               S: A685 OK DELETE Completed
1474 
+               C: A686 LIST "" *
1475 
+               S: * LIST (\Noselect) "/" foo
1476 
+               S: A686 OK LIST completed
1477 
+               C: A687 DELETE foo
1478 
+               S: A687 OK DELETE Completed
1479 
+
1480 
+
1481 
+               C: A82 LIST "" *
1482 
+               S: * LIST () "." blurdybloop
1483 
+               S: * LIST () "." foo
1484 
+               S: * LIST () "." foo.bar
1485 
+               S: A82 OK LIST completed
1486 
+               C: A83 DELETE blurdybloop
1487 
+               S: A83 OK DELETE completed
1488 
+               C: A84 DELETE foo
1489 
+               S: A84 OK DELETE Completed
1490 
+               C: A85 LIST "" *
1491 
+               S: * LIST () "." foo.bar
1492 
+               S: A85 OK LIST completed
1493 
+               C: A86 LIST "" %
1494 
+               S: * LIST (\Noselect) "." foo
1495 
+               S: A86 OK LIST completed
1496 
+
1497 
+6.3.5.  RENAME Command
1498 
+
1499 
+   Arguments:  existing mailbox name
1500 
+               new mailbox name
1501 
+
1502 
+   Responses:  no specific responses for this command
1503 
+
1504 
+   Result:     OK - rename completed
1505 
+               NO - rename failure: can't rename mailbox with that name,
1506 
+                    can't rename to mailbox with that name
1507 
+               BAD - command unknown or arguments invalid
1508 
+
1509 
+      The RENAME command changes the name of a mailbox.  A tagged OK
1510 
+      response is returned only if the mailbox has been renamed.  It is
1511 
+
1512 
+
1513 
+
1514 
+Crispin                     Standards Track                    [Page 27]
1515 
+
1516 
+RFC 2060                       IMAP4rev1                   December 1996
1517 
+
1518 
+
1519 
+      an error to attempt to rename from a mailbox name that does not
1520 
+      exist or to a mailbox name that already exists.  Any error in
1521 
+      renaming will return a tagged NO response.
1522 
+
1523 
+      If the name has inferior hierarchical names, then the inferior
1524 
+      hierarchical names MUST also be renamed.  For example, a rename of
1525 
+      "foo" to "zap" will rename "foo/bar" (assuming "/" is the
1526 
+      hierarchy delimiter character) to "zap/bar".
1527 
+
1528 
+      The value of the highest-used unique identifier of the old mailbox
1529 
+      name MUST be preserved so that a new mailbox created with the same
1530 
+      name will not reuse the identifiers of the former incarnation,
1531 
+      UNLESS the new incarnation has a different unique identifier
1532 
+      validity value.  See the description of the UID command for more
1533 
+      detail.
1534 
+
1535 
+      Renaming INBOX is permitted, and has special behavior.  It moves
1536 
+      all messages in INBOX to a new mailbox with the given name,
1537 
+      leaving INBOX empty.  If the server implementation supports
1538 
+      inferior hierarchical names of INBOX, these are unaffected by a
1539 
+      rename of INBOX.
1540 
+
1541 
+   Examples:   C: A682 LIST "" *
1542 
+               S: * LIST () "/" blurdybloop
1543 
+               S: * LIST (\Noselect) "/" foo
1544 
+               S: * LIST () "/" foo/bar
1545 
+               S: A682 OK LIST completed
1546 
+               C: A683 RENAME blurdybloop sarasoop
1547 
+               S: A683 OK RENAME completed
1548 
+               C: A684 RENAME foo zowie
1549 
+               S: A684 OK RENAME Completed
1550 
+               C: A685 LIST "" *
1551 
+               S: * LIST () "/" sarasoop
1552 
+               S: * LIST (\Noselect) "/" zowie
1553 
+               S: * LIST () "/" zowie/bar
1554 
+               S: A685 OK LIST completed
1555 
+
1556 
+
1557 
+
1558 
+
1559 
+
1560 
+
1561 
+
1562 
+
1563 
+
1564 
+
1565 
+
1566 
+
1567 
+
1568 
+
1569 
+
1570 
+Crispin                     Standards Track                    [Page 28]
1571 
+
1572 
+RFC 2060                       IMAP4rev1                   December 1996
1573 
+
1574 
+
1575 
+               C: Z432 LIST "" *
1576 
+               S: * LIST () "." INBOX
1577 
+               S: * LIST () "." INBOX.bar
1578 
+               S: Z432 OK LIST completed
1579 
+               C: Z433 RENAME INBOX old-mail
1580 
+               S: Z433 OK RENAME completed
1581 
+               C: Z434 LIST "" *
1582 
+               S: * LIST () "." INBOX
1583 
+               S: * LIST () "." INBOX.bar
1584 
+               S: * LIST () "." old-mail
1585 
+               S: Z434 OK LIST completed
1586 
+
1587 
+6.3.6.  SUBSCRIBE Command
1588 
+
1589 
+   Arguments:  mailbox
1590 
+
1591 
+   Responses:  no specific responses for this command
1592 
+
1593 
+   Result:     OK - subscribe completed
1594 
+               NO - subscribe failure: can't subscribe to that name
1595 
+               BAD - command unknown or arguments invalid
1596 
+
1597 
+      The SUBSCRIBE command adds the specified mailbox name to the
1598 
+      server's set of "active" or "subscribed" mailboxes as returned by
1599 
+      the LSUB command.  This command returns a tagged OK response only
1600 
+      if the subscription is successful.
1601 
+
1602 
+      A server MAY validate the mailbox argument to SUBSCRIBE to verify
1603 
+      that it exists.  However, it MUST NOT unilaterally remove an
1604 
+      existing mailbox name from the subscription list even if a mailbox
1605 
+      by that name no longer exists.
1606 
+
1607 
+      Note: this requirement is because some server sites may routinely
1608 
+      remove a mailbox with a well-known name (e.g.  "system-alerts")
1609 
+      after its contents expire, with the intention of recreating it
1610 
+      when new contents are appropriate.
1611 
+
1612 
+   Example:    C: A002 SUBSCRIBE #news.comp.mail.mime
1613 
+               S: A002 OK SUBSCRIBE completed
1614 
+
1615 
+
1616 
+
1617 
+
1618 
+
1619 
+
1620 
+
1621 
+
1622 
+
1623 
+
1624 
+
1625 
+
1626 
+Crispin                     Standards Track                    [Page 29]
1627 
+
1628 
+RFC 2060                       IMAP4rev1                   December 1996
1629 
+
1630 
+
1631 
+6.3.7.  UNSUBSCRIBE Command
1632 
+
1633 
+   Arguments:  mailbox name
1634 
+
1635 
+   Responses:  no specific responses for this command
1636 
+
1637 
+   Result:     OK - unsubscribe completed
1638 
+               NO - unsubscribe failure: can't unsubscribe that name
1639 
+               BAD - command unknown or arguments invalid
1640 
+
1641 
+      The UNSUBSCRIBE command removes the specified mailbox name from
1642 
+      the server's set of "active" or "subscribed" mailboxes as returned
1643 
+      by the LSUB command.  This command returns a tagged OK response
1644 
+      only if the unsubscription is successful.
1645 
+
1646 
+   Example:    C: A002 UNSUBSCRIBE #news.comp.mail.mime
1647 
+               S: A002 OK UNSUBSCRIBE completed
1648 
+
1649 
+6.3..8.  LIST Command
1650 
+
1651 
+   Arguments:  reference name
1652 
+               mailbox name with possible wildcards
1653 
+
1654 
+   Responses:  untagged responses: LIST
1655 
+
1656 
+   Result:     OK - list completed
1657 
+               NO - list failure: can't list that reference or name
1658 
+               BAD - command unknown or arguments invalid
1659 
+
1660 
+      The LIST command returns a subset of names from the complete set
1661 
+      of all names available to the client.  Zero or more untagged LIST
1662 
+      replies are returned, containing the name attributes, hierarchy
1663 
+      delimiter, and name; see the description of the LIST reply for
1664 
+      more detail.
1665 
+
1666 
+      The LIST command SHOULD return its data quickly, without undue
1667 
+      delay.  For example, it SHOULD NOT go to excess trouble to
1668 
+      calculate \Marked or \Unmarked status or perform other processing;
1669 
+      if each name requires 1 second of processing, then a list of 1200
1670 
+      names would take 20 minutes!
1671 
+
1672 
+      An empty ("" string) reference name argument indicates that the
1673 
+      mailbox name is interpreted as by SELECT. The returned mailbox
1674 
+      names MUST match the supplied mailbox name pattern.  A non-empty
1675 
+      reference name argument is the name of a mailbox or a level of
1676 
+      mailbox hierarchy, and indicates a context in which the mailbox
1677 
+      name is interpreted in an implementation-defined manner.
1678 
+
1679 
+
1680 
+
1681 
+
1682 
+Crispin                     Standards Track                    [Page 30]
1683 
+
1684 
+RFC 2060                       IMAP4rev1                   December 1996
1685 
+
1686 
+
1687 
+      An empty ("" string) mailbox name argument is a special request to
1688 
+      return the hierarchy delimiter and the root name of the name given
1689 
+      in the reference.  The value returned as the root MAY be null if
1690 
+      the reference is non-rooted or is null.  In all cases, the
1691 
+      hierarchy delimiter is returned.  This permits a client to get the
1692 
+      hierarchy delimiter even when no mailboxes by that name currently
1693 
+      exist.
1694 
+
1695 
+      The reference and mailbox name arguments are interpreted, in an
1696 
+      implementation-dependent fashion, into a canonical form that
1697 
+      represents an unambiguous left-to-right hierarchy.  The returned
1698 
+      mailbox names will be in the interpreted form.
1699 
+
1700 
+      Any part of the reference argument that is included in the
1701 
+      interpreted form SHOULD prefix the interpreted form.  It SHOULD
1702 
+      also be in the same form as the reference name argument.  This
1703 
+      rule permits the client to determine if the returned mailbox name
1704 
+      is in the context of the reference argument, or if something about
1705 
+      the mailbox argument overrode the reference argument.  Without
1706 
+      this rule, the client would have to have knowledge of the server's
1707 
+      naming semantics including what characters are "breakouts" that
1708 
+      override a naming context.
1709 
+
1710 
+      For example, here are some examples of how references and mailbox
1711 
+      names might be interpreted on a UNIX-based server:
1712 
+
1713 
+               Reference     Mailbox Name  Interpretation
1714 
+               ------------  ------------  --------------
1715 
+               ~smith/Mail/  foo.*         ~smith/Mail/foo.*
1716 
+               archive/      %             archive/%
1717 
+               #news.        comp.mail.*   #news.comp.mail.*
1718 
+               ~smith/Mail/  /usr/doc/foo  /usr/doc/foo
1719 
+               archive/      ~fred/Mail/*  ~fred/Mail/*
1720 
+
1721 
+      The first three examples demonstrate interpretations in the
1722 
+      context of the reference argument.  Note that "~smith/Mail" SHOULD
1723 
+      NOT be transformed into something like "/u2/users/smith/Mail", or
1724 
+      it would be impossible for the client to determine that the
1725 
+      interpretation was in the context of the reference.
1726 
+
1727 
+      The character "*" is a wildcard, and matches zero or more
1728 
+      characters at this position.  The character "%" is similar to "*",
1729 
+      but it does not match a hierarchy delimiter.  If the "%" wildcard
1730 
+      is the last character of a mailbox name argument, matching levels
1731 
+      of hierarchy are also returned.  If these levels of hierarchy are
1732 
+      not also selectable mailboxes, they are returned with the
1733 
+      \Noselect mailbox name attribute (see the description of the LIST
1734 
+      response for more details).
1735 
+
1736 
+
1737 
+
1738 
+Crispin                     Standards Track                    [Page 31]
1739 
+
1740 
+RFC 2060                       IMAP4rev1                   December 1996
1741 
+
1742 
+
1743 
+      Server implementations are permitted to "hide" otherwise
1744 
+      accessible mailboxes from the wildcard characters, by preventing
1745 
+      certain characters or names from matching a wildcard in certain
1746 
+      situations.  For example, a UNIX-based server might restrict the
1747 
+      interpretation of "*" so that an initial "/" character does not
1748 
+      match.
1749 
+
1750 
+      The special name INBOX is included in the output from LIST, if
1751 
+      INBOX is supported by this server for this user and if the
1752 
+      uppercase string "INBOX" matches the interpreted reference and
1753 
+      mailbox name arguments with wildcards as described above.  The
1754 
+      criteria for omitting INBOX is whether SELECT INBOX will return
1755 
+      failure; it is not relevant whether the user's real INBOX resides
1756 
+      on this or some other server.
1757 
+
1758 
+   Example:    C: A101 LIST "" ""
1759 
+               S: * LIST (\Noselect) "/" ""
1760 
+               S: A101 OK LIST Completed
1761 
+               C: A102 LIST #news.comp.mail.misc ""
1762 
+               S: * LIST (\Noselect) "." #news.
1763 
+               S: A102 OK LIST Completed
1764 
+               C: A103 LIST /usr/staff/jones ""
1765 
+               S: * LIST (\Noselect) "/" /
1766 
+               S: A103 OK LIST Completed
1767 
+               C: A202 LIST ~/Mail/ %
1768 
+               S: * LIST (\Noselect) "/" ~/Mail/foo
1769 
+               S: * LIST () "/" ~/Mail/meetings
1770 
+               S: A202 OK LIST completed
1771 
+
1772 
+6.3.9.  LSUB Command
1773 
+
1774 
+   Arguments:  reference name
1775 
+               mailbox name with possible wildcards
1776 
+
1777 
+   Responses:  untagged responses: LSUB
1778 
+
1779 
+   Result:     OK - lsub completed
1780 
+               NO - lsub failure: can't list that reference or name
1781 
+               BAD - command unknown or arguments invalid
1782 
+
1783 
+      The LSUB command returns a subset of names from the set of names
1784 
+      that the user has declared as being "active" or "subscribed".
1785 
+      Zero or more untagged LSUB replies are returned.  The arguments to
1786 
+      LSUB are in the same form as those for LIST.
1787 
+
1788 
+      A server MAY validate the subscribed names to see if they still
1789 
+      exist.  If a name does not exist, it SHOULD be flagged with the
1790 
+      \Noselect attribute in the LSUB response.  The server MUST NOT
1791 
+
1792 
+
1793 
+
1794 
+Crispin                     Standards Track                    [Page 32]
1795 
+
1796 
+RFC 2060                       IMAP4rev1                   December 1996
1797 
+
1798 
+
1799 
+      unilaterally remove an existing mailbox name from the subscription
1800 
+      list even if a mailbox by that name no longer exists.
1801 
+
1802 
+   Example:    C: A002 LSUB "#news." "comp.mail.*"
1803 
+               S: * LSUB () "." #news.comp.mail.mime
1804 
+               S: * LSUB () "." #news.comp.mail.misc
1805 
+               S: A002 OK LSUB completed
1806 
+
1807 
+6.3.10. STATUS Command
1808 
+
1809 
+   Arguments:  mailbox name
1810 
+               status data item names
1811 
+
1812 
+   Responses:  untagged responses: STATUS
1813 
+
1814 
+   Result:     OK - status completed
1815 
+               NO - status failure: no status for that name
1816 
+               BAD - command unknown or arguments invalid
1817 
+
1818 
+      The STATUS command requests the status of the indicated mailbox.
1819 
+      It does not change the currently selected mailbox, nor does it
1820 
+      affect the state of any messages in the queried mailbox (in
1821 
+      particular, STATUS MUST NOT cause messages to lose the \Recent
1822 
+      flag).
1823 
+
1824 
+      The STATUS command provides an alternative to opening a second
1825 
+      IMAP4rev1 connection and doing an EXAMINE command on a mailbox to
1826 
+      query that mailbox's status without deselecting the current
1827 
+      mailbox in the first IMAP4rev1 connection.
1828 
+
1829 
+      Unlike the LIST command, the STATUS command is not guaranteed to
1830 
+      be fast in its response.  In some implementations, the server is
1831 
+      obliged to open the mailbox read-only internally to obtain certain
1832 
+      status information.  Also unlike the LIST command, the STATUS
1833 
+      command does not accept wildcards.
1834 
+
1835 
+      The currently defined status data items that can be requested are:
1836 
+
1837 
+      MESSAGES       The number of messages in the mailbox.
1838 
+
1839 
+      RECENT         The number of messages with the \Recent flag set.
1840 
+
1841 
+      UIDNEXT        The next UID value that will be assigned to a new
1842 
+                     message in the mailbox.  It is guaranteed that this
1843 
+                     value will not change unless new messages are added
1844 
+                     to the mailbox; and that it will change when new
1845 
+                     messages are added even if those new messages are
1846 
+                     subsequently expunged.
1847 
+
1848 
+
1849 
+
1850 
+Crispin                     Standards Track                    [Page 33]
1851 
+
1852 
+RFC 2060                       IMAP4rev1                   December 1996
1853 
+
1854 
+
1855 
+      UIDVALIDITY    The unique identifier validity value of the
1856 
+                     mailbox.
1857 
+
1858 
+      UNSEEN         The number of messages which do not have the \Seen
1859 
+                     flag set.
1860 
+
1861 
+
1862 
+      Example:    C: A042 STATUS blurdybloop (UIDNEXT MESSAGES)
1863 
+                  S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
1864 
+                  S: A042 OK STATUS completed
1865 
+
1866 
+6.3.11. APPEND Command
1867 
+
1868 
+   Arguments:  mailbox name
1869 
+               OPTIONAL flag parenthesized list
1870 
+               OPTIONAL date/time string
1871 
+               message literal
1872 
+
1873 
+   Responses:  no specific responses for this command
1874 
+
1875 
+   Result:     OK - append completed
1876 
+               NO - append error: can't append to that mailbox, error
1877 
+                    in flags or date/time or message text
1878 
+               BAD - command unknown or arguments invalid
1879 
+
1880 
+      The APPEND command appends the literal argument as a new message
1881 
+      to the end of the specified destination mailbox.  This argument
1882 
+      SHOULD be in the format of an [RFC-822] message.  8-bit characters
1883 
+      are permitted in the message.  A server implementation that is
1884 
+      unable to preserve 8-bit data properly MUST be able to reversibly
1885 
+      convert 8-bit APPEND data to 7-bit using a [MIME-IMB] content
1886 
+      transfer encoding.
1887 
+
1888 
+      Note: There MAY be exceptions, e.g. draft messages, in which
1889 
+      required [RFC-822] header lines are omitted in the message literal
1890 
+      argument to APPEND.  The full implications of doing so MUST be
1891 
+      understood and carefully weighed.
1892 
+
1893 
+   If a flag parenthesized list is specified, the flags SHOULD be set in
1894 
+   the resulting message; otherwise, the flag list of the resulting
1895 
+   message is set empty by default.
1896 
+
1897 
+   If a date_time is specified, the internal date SHOULD be set in the
1898 
+   resulting message; otherwise, the internal date of the resulting
1899 
+   message is set to the current date and time by default.
1900 
+
1901 
+
1902 
+
1903 
+
1904 
+
1905 
+
1906 
+Crispin                     Standards Track                    [Page 34]
1907 
+
1908 
+RFC 2060                       IMAP4rev1                   December 1996
1909 
+
1910 
+
1911 
+   If the append is unsuccessful for any reason, the mailbox MUST be
1912 
+   restored to its state before the APPEND attempt; no partial appending
1913 
+   is permitted.
1914 
+
1915 
+   If the destination mailbox does not exist, a server MUST return an
1916 
+   error, and MUST NOT automatically create the mailbox.  Unless it is
1917 
+   certain that the destination mailbox can not be created, the server
1918 
+   MUST send the response code "[TRYCREATE]" as the prefix of the text
1919 
+   of the tagged NO response.  This gives a hint to the client that it
1920 
+   can attempt a CREATE command and retry the APPEND if the CREATE is
1921 
+   successful.
1922 
+
1923 
+   If the mailbox is currently selected, the normal new mail actions
1924 
+   SHOULD occur.  Specifically, the server SHOULD notify the client
1925 
+   immediately via an untagged EXISTS response.  If the server does not
1926 
+   do so, the client MAY issue a NOOP command (or failing that, a CHECK
1927 
+   command) after one or more APPEND commands.
1928 
+
1929 
+   Example:    C: A003 APPEND saved-messages (\Seen) {310}
1930 
+               C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
1931 
+               C: From: Fred Foobar <foobar@Blurdybloop.COM>
1932 
+               C: Subject: afternoon meeting
1933 
+               C: To: mooch@owatagu.siam.edu
1934 
+               C: Message-Id: <B27397-0100000@Blurdybloop.COM>
1935 
+               C: MIME-Version: 1.0
1936 
+               C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
1937 
+               C:
1938 
+               C: Hello Joe, do you think we can meet at 3:30 tomorrow?
1939 
+               C:
1940 
+               S: A003 OK APPEND completed
1941 
+
1942 
+      Note: the APPEND command is not used for message delivery, because
1943 
+      it does not provide a mechanism to transfer [SMTP] envelope
1944 
+      information.
1945 
+
1946 
+6.4.    Client Commands - Selected State
1947 
+
1948 
+   In selected state, commands that manipulate messages in a mailbox are
1949 
+   permitted.
1950 
+
1951 
+   In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT),
1952 
+   and the authenticated state commands (SELECT, EXAMINE, CREATE,
1953 
+   DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, and
1954 
+   APPEND), the following commands are valid in the selected state:
1955 
+   CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, STORE, COPY, and UID.
1956 
+
1957 
+
1958 
+
1959 
+
1960 
+
1961 
+
1962 
+Crispin                     Standards Track                    [Page 35]
1963 
+
1964 
+RFC 2060                       IMAP4rev1                   December 1996
1965 
+
1966 
+
1967 
+6.4.1.  CHECK Command
1968 
+
1969 
+   Arguments:  none
1970 
+
1971 
+   Responses:  no specific responses for this command
1972 
+
1973 
+   Result:     OK - check completed
1974 
+               BAD - command unknown or arguments invalid
1975 
+
1976 
+      The CHECK command requests a checkpoint of the currently selected
1977 
+      mailbox.  A checkpoint refers to any implementation-dependent
1978 
+      housekeeping associated with the mailbox (e.g. resolving the
1979 
+      server's in-memory state of the mailbox with the state on its
1980 
+      disk) that is not normally executed as part of each command.  A
1981 
+      checkpoint MAY take a non-instantaneous amount of real time to
1982 
+      complete.  If a server implementation has no such housekeeping
1983 
+      considerations, CHECK is equivalent to NOOP.
1984 
+
1985 
+      There is no guarantee that an EXISTS untagged response will happen
1986 
+      as a result of CHECK.  NOOP, not CHECK, SHOULD be used for new
1987 
+      mail polling.
1988 
+
1989 
+   Example:    C: FXXZ CHECK
1990 
+               S: FXXZ OK CHECK Completed
1991 
+
1992 
+6.4.2.  CLOSE Command
1993 
+
1994 
+   Arguments:  none
1995 
+
1996 
+   Responses:  no specific responses for this command
1997 
+
1998 
+   Result:     OK - close completed, now in authenticated state
1999 
+               NO - close failure: no mailbox selected
2000 
+               BAD - command unknown or arguments invalid
2001 
+
2002 
+      The CLOSE command permanently removes from the currently selected
2003 
+      mailbox all messages that have the \Deleted flag set, and returns
2004 
+      to authenticated state from selected state.  No untagged EXPUNGE
2005 
+      responses are sent.
2006 
+
2007 
+      No messages are removed, and no error is given, if the mailbox is
2008 
+      selected by an EXAMINE command or is otherwise selected read-only.
2009 
+
2010 
+      Even if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT
2011 
+      command MAY be issued without previously issuing a CLOSE command.
2012 
+      The SELECT, EXAMINE, and LOGOUT commands implicitly close the
2013 
+      currently selected mailbox without doing an expunge.  However,
2014 
+      when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT
2015 
+
2016 
+
2017 
+
2018 
+Crispin                     Standards Track                    [Page 36]
2019 
+
2020 
+RFC 2060                       IMAP4rev1                   December 1996
2021 
+
2022 
+
2023 
+      sequence is considerably faster than an EXPUNGE-LOGOUT or
2024 
+      EXPUNGE-SELECT because no untagged EXPUNGE responses (which the
2025 
+      client would probably ignore) are sent.
2026 
+
2027 
+   Example:    C: A341 CLOSE
2028 
+               S: A341 OK CLOSE completed
2029 
+
2030 
+6.4.3.  EXPUNGE Command
2031 
+
2032 
+   Arguments:  none
2033 
+
2034 
+   Responses:  untagged responses: EXPUNGE
2035 
+
2036 
+   Result:     OK - expunge completed
2037 
+               NO - expunge failure: can't expunge (e.g. permission
2038 
+                    denied)
2039 
+               BAD - command unknown or arguments invalid
2040 
+
2041 
+      The EXPUNGE command permanently removes from the currently
2042 
+      selected mailbox all messages that have the \Deleted flag set.
2043 
+      Before returning an OK to the client, an untagged EXPUNGE response
2044 
+      is sent for each message that is removed.
2045 
+
2046 
+   Example:    C: A202 EXPUNGE
2047 
+               S: * 3 EXPUNGE
2048 
+               S: * 3 EXPUNGE
2049 
+               S: * 5 EXPUNGE
2050 
+               S: * 8 EXPUNGE
2051 
+               S: A202 OK EXPUNGE completed
2052 
+
2053 
+      Note: in this example, messages 3, 4, 7, and 11 had the
2054 
+      \Deleted flag set.  See the description of the EXPUNGE
2055 
+      response for further explanation.
2056 
+
2057 
+6.4.4.  SEARCH Command
2058 
+
2059 
+   Arguments:  OPTIONAL [CHARSET] specification
2060 
+               searching criteria (one or more)
2061 
+
2062 
+   Responses:  REQUIRED untagged response: SEARCH
2063 
+
2064 
+   Result:     OK - search completed
2065 
+               NO - search error: can't search that [CHARSET] or
2066 
+                    criteria
2067 
+               BAD - command unknown or arguments invalid
2068 
+
2069 
+
2070 
+
2071 
+
2072 
+
2073 
+
2074 
+Crispin                     Standards Track                    [Page 37]
2075 
+
2076 
+RFC 2060                       IMAP4rev1                   December 1996
2077 
+
2078 
+
2079 
+      The SEARCH command searches the mailbox for messages that match
2080 
+      the given searching criteria.  Searching criteria consist of one
2081 
+      or more search keys.  The untagged SEARCH response from the server
2082 
+      contains a listing of message sequence numbers corresponding to
2083 
+      those messages that match the searching criteria.
2084 
+
2085 
+      When multiple keys are specified, the result is the intersection
2086 
+      (AND function) of all the messages that match those keys.  For
2087 
+      example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers
2088 
+      to all deleted messages from Smith that were placed in the mailbox
2089 
+      since February 1, 1994.  A search key can also be a parenthesized
2090 
+      list of one or more search keys (e.g. for use with the OR and NOT
2091 
+      keys).
2092 
+
2093 
+      Server implementations MAY exclude [MIME-IMB] body parts with
2094 
+      terminal content media types other than TEXT and MESSAGE from
2095 
+      consideration in SEARCH matching.
2096 
+
2097 
+      The OPTIONAL [CHARSET] specification consists of the word
2098 
+      "CHARSET" followed by a registered [CHARSET].  It indicates the
2099 
+      [CHARSET] of the strings that appear in the search criteria.
2100 
+      [MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in
2101 
+      [RFC-822]/[MIME-IMB] headers, MUST be decoded before comparing
2102 
+      text in a [CHARSET] other than US-ASCII.  US-ASCII MUST be
2103 
+      supported; other [CHARSET]s MAY be supported.  If the server does
2104 
+      not support the specified [CHARSET], it MUST return a tagged NO
2105 
+      response (not a BAD).
2106 
+
2107 
+      In all search keys that use strings, a message matches the key if
2108 
+      the string is a substring of the field.  The matching is case-
2109 
+      insensitive.
2110 
+
2111 
+      The defined search keys are as follows.  Refer to the Formal
2112 
+      Syntax section for the precise syntactic definitions of the
2113 
+      arguments.
2114 
+
2115 
+      <message set>  Messages with message sequence numbers
2116 
+                     corresponding to the specified message sequence
2117 
+                     number set
2118 
+
2119 
+      ALL            All messages in the mailbox; the default initial
2120 
+                     key for ANDing.
2121 
+
2122 
+      ANSWERED       Messages with the \Answered flag set.
2123 
+
2124 
+      BCC <string>   Messages that contain the specified string in the
2125 
+                     envelope structure's BCC field.
2126 
+
2127 
+
2128 
+
2129 
+
2130 
+Crispin                     Standards Track                    [Page 38]
2131 
+
2132 
+RFC 2060                       IMAP4rev1                   December 1996
2133 
+
2134 
+
2135 
+      BEFORE <date>  Messages whose internal date is earlier than the
2136 
+                     specified date.
2137 
+
2138 
+      BODY <string>  Messages that contain the specified string in the
2139 
+                     body of the message.
2140 
+
2141 
+      CC <string>    Messages that contain the specified string in the
2142 
+                     envelope structure's CC field.
2143 
+
2144 
+      DELETED        Messages with the \Deleted flag set.
2145 
+
2146 
+      DRAFT          Messages with the \Draft flag set.
2147 
+
2148 
+      FLAGGED        Messages with the \Flagged flag set.
2149 
+
2150 
+      FROM <string>  Messages that contain the specified string in the
2151 
+                     envelope structure's FROM field.
2152 
+
2153 
+      HEADER <field-name> <string>
2154 
+                     Messages that have a header with the specified
2155 
+                     field-name (as defined in [RFC-822]) and that
2156 
+                     contains the specified string in the [RFC-822]
2157 
+                     field-body.
2158 
+
2159 
+      KEYWORD <flag> Messages with the specified keyword set.
2160 
+
2161 
+      LARGER <n>     Messages with an [RFC-822] size larger than the
2162 
+                     specified number of octets.
2163 
+
2164 
+      NEW            Messages that have the \Recent flag set but not the
2165 
+                     \Seen flag.  This is functionally equivalent to
2166 
+                     "(RECENT UNSEEN)".
2167 
+
2168 
+      NOT <search-key>
2169 
+                     Messages that do not match the specified search
2170 
+                     key.
2171 
+
2172 
+      OLD            Messages that do not have the \Recent flag set.
2173 
+                     This is functionally equivalent to "NOT RECENT" (as
2174 
+                     opposed to "NOT NEW").
2175 
+
2176 
+      ON <date>      Messages whose internal date is within the
2177 
+                     specified date.
2178 
+
2179 
+      OR <search-key1> <search-key2>
2180 
+                     Messages that match either search key.
2181 
+
2182 
+      RECENT         Messages that have the \Recent flag set.
2183 
+
2184 
+
2185 
+
2186 
+Crispin                     Standards Track                    [Page 39]
2187 
+
2188 
+RFC 2060                       IMAP4rev1                   December 1996
2189 
+
2190 
+
2191 
+      SEEN           Messages that have the \Seen flag set.
2192 
+
2193 
+      SENTBEFORE <date>
2194 
+                     Messages whose [RFC-822] Date: header is earlier
2195 
+                     than the specified date.
2196 
+
2197 
+      SENTON <date>  Messages whose [RFC-822] Date: header is within the
2198 
+                     specified date.
2199 
+
2200 
+      SENTSINCE <date>
2201 
+                     Messages whose [RFC-822] Date: header is within or
2202 
+                     later than the specified date.
2203 
+
2204 
+      SINCE <date>   Messages whose internal date is within or later
2205 
+                     than the specified date.
2206 
+
2207 
+      SMALLER <n>    Messages with an [RFC-822] size smaller than the
2208 
+                     specified number of octets.
2209 
+
2210 
+      SUBJECT <string>
2211 
+                     Messages that contain the specified string in the
2212 
+                     envelope structure's SUBJECT field.
2213 
+
2214 
+      TEXT <string>  Messages that contain the specified string in the
2215 
+                     header or body of the message.
2216 
+
2217 
+      TO <string>    Messages that contain the specified string in the
2218 
+                     envelope structure's TO field.
2219 
+
2220 
+      UID <message set>
2221 
+                     Messages with unique identifiers corresponding to
2222 
+                     the specified unique identifier set.
2223 
+
2224 
+      UNANSWERED     Messages that do not have the \Answered flag set.
2225 
+
2226 
+      UNDELETED      Messages that do not have the \Deleted flag set.
2227 
+
2228 
+      UNDRAFT        Messages that do not have the \Draft flag set.
2229 
+
2230 
+      UNFLAGGED      Messages that do not have the \Flagged flag set.
2231 
+
2232 
+      UNKEYWORD <flag>
2233 
+                     Messages that do not have the specified keyword
2234 
+                     set.
2235 
+
2236 
+      UNSEEN         Messages that do not have the \Seen flag set.
2237 
+
2238 
+
2239 
+
2240 
+
2241 
+
2242 
+Crispin                     Standards Track                    [Page 40]
2243 
+
2244 
+RFC 2060                       IMAP4rev1                   December 1996
2245 
+
2246 
+
2247 
+   Example:    C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"
2248 
+               S: * SEARCH 2 84 882
2249 
+               S: A282 OK SEARCH completed
2250 
+
2251 
+6.4.5.  FETCH Command
2252 
+
2253 
+   Arguments:  message set
2254 
+               message data item names
2255 
+
2256 
+   Responses:  untagged responses: FETCH
2257 
+
2258 
+   Result:     OK - fetch completed
2259 
+               NO - fetch error: can't fetch that data
2260 
+               BAD - command unknown or arguments invalid
2261 
+
2262 
+      The FETCH command retrieves data associated with a message in the
2263 
+      mailbox.  The data items to be fetched can be either a single atom
2264 
+      or a parenthesized list.
2265 
+
2266 
+      The currently defined data items that can be fetched are:
2267 
+
2268 
+      ALL            Macro equivalent to: (FLAGS INTERNALDATE
2269 
+                     RFC822.SIZE ENVELOPE)
2270 
+
2271 
+      BODY           Non-extensible form of BODYSTRUCTURE.
2272 
+
2273 
+      BODY[<section>]<<partial>>
2274 
+                     The text of a particular body section.  The section
2275 
+                     specification is a set of zero or more part
2276 
+                     specifiers delimited by periods.  A part specifier
2277 
+                     is either a part number or one of the following:
2278 
+                     HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, MIME, and
2279 
+                     TEXT.  An empty section specification refers to the
2280 
+                     entire message, including the header.
2281 
+
2282 
+                     Every message has at least one part number.
2283 
+                     Non-[MIME-IMB] messages, and non-multipart
2284 
+                     [MIME-IMB] messages with no encapsulated message,
2285 
+                     only have a part 1.
2286 
+
2287 
+                     Multipart messages are assigned consecutive part
2288 
+                     numbers, as they occur in the message.  If a
2289 
+                     particular part is of type message or multipart,
2290 
+                     its parts MUST be indicated by a period followed by
2291 
+                     the part number within that nested multipart part.
2292 
+
2293 
+
2294 
+
2295 
+
2296 
+
2297 
+
2298 
+Crispin                     Standards Track                    [Page 41]
2299 
+
2300 
+RFC 2060                       IMAP4rev1                   December 1996
2301 
+
2302 
+
2303 
+                     A part of type MESSAGE/RFC822 also has nested part
2304 
+                     numbers, referring to parts of the MESSAGE part's
2305 
+                     body.
2306 
+
2307 
+                     The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and
2308 
+                     TEXT part specifiers can be the sole part specifier
2309 
+                     or can be prefixed by one or more numeric part
2310 
+                     specifiers, provided that the numeric part
2311 
+                     specifier refers to a part of type MESSAGE/RFC822.
2312 
+                     The MIME part specifier MUST be prefixed by one or
2313 
+                     more numeric part specifiers.
2314 
+
2315 
+                     The HEADER, HEADER.FIELDS, and HEADER.FIELDS.NOT
2316 
+                     part specifiers refer to the [RFC-822] header of
2317 
+                     the message or of an encapsulated [MIME-IMT]
2318 
+                     MESSAGE/RFC822 message.  HEADER.FIELDS and
2319 
+                     HEADER.FIELDS.NOT are followed by a list of
2320 
+                     field-name (as defined in [RFC-822]) names, and
2321 
+                     return a subset of the header.  The subset returned
2322 
+                     by HEADER.FIELDS contains only those header fields
2323 
+                     with a field-name that matches one of the names in
2324 
+                     the list; similarly, the subset returned by
2325 
+                     HEADER.FIELDS.NOT contains only the header fields
2326 
+                     with a non-matching field-name.  The field-matching
2327 
+                     is case-insensitive but otherwise exact.  In all
2328 
+                     cases, the delimiting blank line between the header
2329 
+                     and the body is always included.
2330 
+
2331 
+                     The MIME part specifier refers to the [MIME-IMB]
2332 
+                     header for this part.
2333 
+
2334 
+                     The TEXT part specifier refers to the text body of
2335 
+                     the message, omitting the [RFC-822] header.
2336 
+
2337 
+
2338 
+
2339 
+
2340 
+
2341 
+
2342 
+
2343 
+
2344 
+
2345 
+
2346 
+
2347 
+
2348 
+
2349 
+
2350 
+
2351 
+
2352 
+
2353 
+
2354 
+Crispin                     Standards Track                    [Page 42]
2355 
+
2356 
+RFC 2060                       IMAP4rev1                   December 1996
2357 
+
2358 
+
2359 
+                       Here is an example of a complex message
2360 
+                       with some of its part specifiers:
2361 
+
2362 
+                        HEADER     ([RFC-822] header of the message)
2363 
+                        TEXT       MULTIPART/MIXED
2364 
+                        1          TEXT/PLAIN
2365 
+                        2          APPLICATION/OCTET-STREAM
2366 
+                        3          MESSAGE/RFC822
2367 
+                        3.HEADER   ([RFC-822] header of the message)
2368 
+                        3.TEXT     ([RFC-822] text body of the message)
2369 
+                        3.1        TEXT/PLAIN
2370 
+                        3.2        APPLICATION/OCTET-STREAM
2371 
+                        4          MULTIPART/MIXED
2372 
+                        4.1        IMAGE/GIF
2373 
+                        4.1.MIME   ([MIME-IMB] header for the IMAGE/GIF)
2374 
+                        4.2        MESSAGE/RFC822
2375 
+                        4.2.HEADER ([RFC-822] header of the message)
2376 
+                        4.2.TEXT   ([RFC-822] text body of the message)
2377 
+                        4.2.1      TEXT/PLAIN
2378 
+                        4.2.2      MULTIPART/ALTERNATIVE
2379 
+                        4.2.2.1    TEXT/PLAIN
2380 
+                        4.2.2.2    TEXT/RICHTEXT
2381 
+
2382 
+
2383 
+                     It is possible to fetch a substring of the
2384 
+                     designated text.  This is done by appending an open
2385 
+                     angle bracket ("<"), the octet position of the
2386 
+                     first desired octet, a period, the maximum number
2387 
+                     of octets desired, and a close angle bracket (">")
2388 
+                     to the part specifier.  If the starting octet is
2389 
+                     beyond the end of the text, an empty string is
2390 
+                     returned.
2391 
+
2392 
+                     Any partial fetch that attempts to read beyond the
2393 
+                     end of the text is truncated as appropriate.  A
2394 
+                     partial fetch that starts at octet 0 is returned as
2395 
+                     a partial fetch, even if this truncation happened.
2396 
+
2397 
+                          Note: this means that BODY[]<0.2048> of a
2398 
+                          1500-octet message will return BODY[]<0>
2399 
+                          with a literal of size 1500, not BODY[].
2400 
+
2401 
+                          Note: a substring fetch of a
2402 
+                          HEADER.FIELDS or HEADER.FIELDS.NOT part
2403 
+                          specifier is calculated after subsetting
2404 
+                          the header.
2405 
+
2406 
+
2407 
+
2408 
+
2409 
+
2410 
+Crispin                     Standards Track                    [Page 43]
2411 
+
2412 
+RFC 2060                       IMAP4rev1                   December 1996
2413 
+
2414 
+
2415 
+                     The \Seen flag is implicitly set; if this causes
2416 
+                     the flags to change they SHOULD be included as part
2417 
+                     of the FETCH responses.
2418 
+
2419 
+      BODY.PEEK[<section>]<<partial>>
2420 
+                     An alternate form of BODY[<section>] that does not
2421 
+                     implicitly set the \Seen flag.
2422 
+
2423 
+      BODYSTRUCTURE  The [MIME-IMB] body structure of the message.  This
2424 
+                     is computed by the server by parsing the [MIME-IMB]
2425 
+                     header fields in the [RFC-822] header and
2426 
+                     [MIME-IMB] headers.
2427 
+
2428 
+      ENVELOPE       The envelope structure of the message.  This is
2429 
+                     computed by the server by parsing the [RFC-822]
2430 
+                     header into the component parts, defaulting various
2431 
+                     fields as necessary.
2432 
+
2433 
+      FAST           Macro equivalent to: (FLAGS INTERNALDATE
2434 
+                     RFC822.SIZE)
2435 
+
2436 
+      FLAGS          The flags that are set for this message.
2437 
+
2438 
+      FULL           Macro equivalent to: (FLAGS INTERNALDATE
2439 
+                     RFC822.SIZE ENVELOPE BODY)
2440 
+
2441 
+      INTERNALDATE   The internal date of the message.
2442 
+
2443 
+      RFC822         Functionally equivalent to BODY[], differing in the
2444 
+                     syntax of the resulting untagged FETCH data (RFC822
2445 
+                     is returned).
2446 
+
2447 
+      RFC822.HEADER  Functionally equivalent to BODY.PEEK[HEADER],
2448 
+                     differing in the syntax of the resulting untagged
2449 
+                     FETCH data (RFC822.HEADER is returned).
2450 
+
2451 
+      RFC822.SIZE    The [RFC-822] size of the message.
2452 
+
2453 
+      RFC822.TEXT    Functionally equivalent to BODY[TEXT], differing in
2454 
+                     the syntax of the resulting untagged FETCH data
2455 
+                     (RFC822.TEXT is returned).
2456 
+
2457 
+      UID            The unique identifier for the message.
2458 
+
2459 
+
2460 
+
2461 
+
2462 
+
2463 
+
2464 
+
2465 
+
2466 
+Crispin                     Standards Track                    [Page 44]
2467 
+
2468 
+RFC 2060                       IMAP4rev1                   December 1996
2469 
+
2470 
+
2471 
+   Example:    C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
2472 
+               S: * 2 FETCH ....
2473 
+               S: * 3 FETCH ....
2474 
+               S: * 4 FETCH ....
2475 
+               S: A654 OK FETCH completed
2476 
+
2477 
+6.4.6.  STORE Command
2478 
+
2479 
+   Arguments:  message set
2480 
+               message data item name
2481 
+               value for message data item
2482 
+
2483 
+   Responses:  untagged responses: FETCH
2484 
+
2485 
+   Result:     OK - store completed
2486 
+               NO - store error: can't store that data
2487 
+               BAD - command unknown or arguments invalid
2488 
+
2489 
+      The STORE command alters data associated with a message in the
2490 
+      mailbox.  Normally, STORE will return the updated value of the
2491 
+      data with an untagged FETCH response.  A suffix of ".SILENT" in
2492 
+      the data item name prevents the untagged FETCH, and the server
2493 
+      SHOULD assume that the client has determined the updated value
2494 
+      itself or does not care about the updated value.
2495 
+
2496 
+         Note: regardless of whether or not the ".SILENT" suffix was
2497 
+         used, the server SHOULD send an untagged FETCH response if a
2498 
+         change to a message's flags from an external source is
2499 
+         observed.  The intent is that the status of the flags is
2500 
+         determinate without a race condition.
2501 
+
2502 
+      The currently defined data items that can be stored are:
2503 
+
2504 
+      FLAGS <flag list>
2505 
+                     Replace the flags for the message with the
2506 
+                     argument.  The new value of the flags are returned
2507 
+                     as if a FETCH of those flags was done.
2508 
+
2509 
+      FLAGS.SILENT <flag list>
2510 
+                     Equivalent to FLAGS, but without returning a new
2511 
+                     value.
2512 
+
2513 
+      +FLAGS <flag list>
2514 
+                     Add the argument to the flags for the message.  The
2515 
+                     new value of the flags are returned as if a FETCH
2516 
+                     of those flags was done.
2517 
+
2518 
+
2519 
+
2520 
+
2521 
+
2522 
+Crispin                     Standards Track                    [Page 45]
2523 
+
2524 
+RFC 2060                       IMAP4rev1                   December 1996
2525 
+
2526 
+
2527 
+      +FLAGS.SILENT <flag list>
2528 
+                     Equivalent to +FLAGS, but without returning a new
2529 
+                     value.
2530 
+
2531 
+      -FLAGS <flag list>
2532 
+                     Remove the argument from the flags for the message.
2533 
+                     The new value of the flags are returned as if a
2534 
+                     FETCH of those flags was done.
2535 
+
2536 
+      -FLAGS.SILENT <flag list>
2537 
+                     Equivalent to -FLAGS, but without returning a new
2538 
+                     value.
2539 
+
2540 
+   Example:    C: A003 STORE 2:4 +FLAGS (\Deleted)
2541 
+               S: * 2 FETCH FLAGS (\Deleted \Seen)
2542 
+               S: * 3 FETCH FLAGS (\Deleted)
2543 
+               S: * 4 FETCH FLAGS (\Deleted \Flagged \Seen)
2544 
+               S: A003 OK STORE completed
2545 
+
2546 
+6.4.7.  COPY Command
2547 
+
2548 
+   Arguments:  message set
2549 
+               mailbox name
2550 
+
2551 
+   Responses:  no specific responses for this command
2552 
+
2553 
+   Result:     OK - copy completed
2554 
+               NO - copy error: can't copy those messages or to that
2555 
+                    name
2556 
+               BAD - command unknown or arguments invalid
2557 
+
2558 
+      The COPY command copies the specified message(s) to the end of the
2559 
+      specified destination mailbox.  The flags and internal date of the
2560 
+      message(s) SHOULD be preserved in the copy.
2561 
+
2562 
+      If the destination mailbox does not exist, a server SHOULD return
2563 
+      an error.  It SHOULD NOT automatically create the mailbox.  Unless
2564 
+      it is certain that the destination mailbox can not be created, the
2565 
+      server MUST send the response code "[TRYCREATE]" as the prefix of
2566 
+      the text of the tagged NO response.  This gives a hint to the
2567 
+      client that it can attempt a CREATE command and retry the COPY if
2568 
+      the CREATE is successful.
2569 
+
2570 
+
2571 
+
2572 
+
2573 
+
2574 
+
2575 
+
2576 
+
2577 
+
2578 
+Crispin                     Standards Track                    [Page 46]
2579 
+
2580 
+RFC 2060                       IMAP4rev1                   December 1996
2581 
+
2582 
+
2583 
+      If the COPY command is unsuccessful for any reason, server
2584 
+      implementations MUST restore the destination mailbox to its state
2585 
+      before the COPY attempt.
2586 
+
2587 
+   Example:    C: A003 COPY 2:4 MEETING
2588 
+               S: A003 OK COPY completed
2589 
+
2590 
+6.4.8.  UID Command
2591 
+
2592 
+   Arguments:  command name
2593 
+               command arguments
2594 
+
2595 
+   Responses:  untagged responses: FETCH, SEARCH
2596 
+
2597 
+   Result:     OK - UID command completed
2598 
+               NO - UID command error
2599 
+               BAD - command unknown or arguments invalid
2600 
+
2601 
+      The UID command has two forms.  In the first form, it takes as its
2602 
+      arguments a COPY, FETCH, or STORE command with arguments
2603 
+      appropriate for the associated command.  However, the numbers in
2604 
+      the message set argument are unique identifiers instead of message
2605 
+      sequence numbers.
2606 
+
2607 
+      In the second form, the UID command takes a SEARCH command with
2608 
+      SEARCH command arguments.  The interpretation of the arguments is
2609 
+      the same as with SEARCH; however, the numbers returned in a SEARCH
2610 
+      response for a UID SEARCH command are unique identifiers instead
2611 
+      of message sequence numbers.  For example, the command UID SEARCH
2612 
+      1:100 UID 443:557 returns the unique identifiers corresponding to
2613 
+      the intersection of the message sequence number set 1:100 and the
2614 
+      UID set 443:557.
2615 
+
2616 
+      Message set ranges are permitted; however, there is no guarantee
2617 
+      that unique identifiers be contiguous.  A non-existent unique
2618 
+      identifier within a message set range is ignored without any error
2619 
+      message generated.
2620 
+
2621 
+      The number after the "*" in an untagged FETCH response is always a
2622 
+      message sequence number, not a unique identifier, even for a UID
2623 
+      command response.  However, server implementations MUST implicitly
2624 
+      include the UID message data item as part of any FETCH response
2625 
+      caused by a UID command, regardless of whether a UID was specified
2626 
+      as a message data item to the FETCH.
2627 
+
2628 
+
2629 
+
2630 
+
2631 
+
2632 
+
2633 
+
2634 
+Crispin                     Standards Track                    [Page 47]
2635 
+
2636 
+RFC 2060                       IMAP4rev1                   December 1996
2637 
+
2638 
+
2639 
+   Example:    C: A999 UID FETCH 4827313:4828442 FLAGS
2640 
+               S: * 23 FETCH (FLAGS (\Seen) UID 4827313)
2641 
+               S: * 24 FETCH (FLAGS (\Seen) UID 4827943)
2642 
+               S: * 25 FETCH (FLAGS (\Seen) UID 4828442)
2643 
+               S: A999 UID FETCH completed
2644 
+
2645 
+6.5.    Client Commands - Experimental/Expansion
2646 
+
2647 
+6.5.1.  X<atom> Command
2648 
+
2649 
+   Arguments:  implementation defined
2650 
+
2651 
+   Responses:  implementation defined
2652 
+
2653 
+   Result:     OK - command completed
2654 
+               NO - failure
2655 
+               BAD - command unknown or arguments invalid
2656 
+
2657 
+      Any command prefixed with an X is an experimental command.
2658 
+      Commands which are not part of this specification, a standard or
2659 
+      standards-track revision of this specification, or an IESG-
2660 
+      approved experimental protocol, MUST use the X prefix.
2661 
+
2662 
+      Any added untagged responses issued by an experimental command
2663 
+      MUST also be prefixed with an X.  Server implementations MUST NOT
2664 
+      send any such untagged responses, unless the client requested it
2665 
+      by issuing the associated experimental command.
2666 
+
2667 
+   Example:    C: a441 CAPABILITY
2668 
+               S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4 XPIG-LATIN
2669 
+               S: a441 OK CAPABILITY completed
2670 
+               C: A442 XPIG-LATIN
2671 
+               S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay
2672 
+               S: A442 OK XPIG-LATIN ompleted-cay
2673 
+
2674 
+7.      Server Responses
2675 
+
2676 
+   Server responses are in three forms: status responses, server data,
2677 
+   and command continuation request.  The information contained in a
2678 
+   server response, identified by "Contents:" in the response
2679 
+   descriptions below, is described by function, not by syntax.  The
2680 
+   precise syntax of server responses is described in the Formal Syntax
2681 
+   section.
2682 
+
2683 
+   The client MUST be prepared to accept any response at all times.
2684 
+
2685 
+
2686 
+
2687 
+
2688 
+
2689 
+
2690 
+Crispin                     Standards Track                    [Page 48]
2691 
+
2692 
+RFC 2060                       IMAP4rev1                   December 1996
2693 
+
2694 
+
2695 
+   Status responses can be tagged or untagged.  Tagged status responses
2696 
+   indicate the completion result (OK, NO, or BAD status) of a client
2697 
+   command, and have a tag matching the command.
2698 
+
2699 
+   Some status responses, and all server data, are untagged.  An
2700 
+   untagged response is indicated by the token "*" instead of a tag.
2701 
+   Untagged status responses indicate server greeting, or server status
2702 
+   that does not indicate the completion of a command (for example, an
2703 
+   impending system shutdown alert).  For historical reasons, untagged
2704 
+   server data responses are also called "unsolicited data", although
2705 
+   strictly speaking only unilateral server data is truly "unsolicited".
2706 
+
2707 
+   Certain server data MUST be recorded by the client when it is
2708 
+   received; this is noted in the description of that data.  Such data
2709 
+   conveys critical information which affects the interpretation of all
2710 
+   subsequent commands and responses (e.g. updates reflecting the
2711 
+   creation or destruction of messages).
2712 
+
2713 
+   Other server data SHOULD be recorded for later reference; if the
2714 
+   client does not need to record the data, or if recording the data has
2715 
+   no obvious purpose (e.g. a SEARCH response when no SEARCH command is
2716 
+   in progress), the data SHOULD be ignored.
2717 
+
2718 
+   An example of unilateral untagged server data occurs when the IMAP
2719 
+   connection is in selected state.  In selected state, the server
2720 
+   checks the mailbox for new messages as part of command execution.
2721 
+   Normally, this is part of the execution of every command; hence, a
2722 
+   NOOP command suffices to check for new messages.  If new messages are
2723 
+   found, the server sends untagged EXISTS and RECENT responses
2724 
+   reflecting the new size of the mailbox.  Server implementations that
2725 
+   offer multiple simultaneous access to the same mailbox SHOULD also
2726 
+   send appropriate unilateral untagged FETCH and EXPUNGE responses if
2727 
+   another agent changes the state of any message flags or expunges any
2728 
+   messages.
2729 
+
2730 
+   Command continuation request responses use the token "+" instead of a
2731 
+   tag.  These responses are sent by the server to indicate acceptance
2732 
+   of an incomplete client command and readiness for the remainder of
2733 
+   the command.
2734 
+
2735 
+7.1.    Server Responses - Status Responses
2736 
+
2737 
+   Status responses are OK, NO, BAD, PREAUTH and BYE.  OK, NO, and BAD
2738 
+   may be tagged or untagged.  PREAUTH and BYE are always untagged.
2739 
+
2740 
+   Status responses MAY include an OPTIONAL "response code".  A response
2741 
+   code consists of data inside square brackets in the form of an atom,
2742 
+   possibly followed by a space and arguments.  The response code
2743 
+
2744 
+
2745 
+
2746 
+Crispin                     Standards Track                    [Page 49]
2747 
+
2748 
+RFC 2060                       IMAP4rev1                   December 1996
2749 
+
2750 
+
2751 
+   contains additional information or status codes for client software
2752 
+   beyond the OK/NO/BAD condition, and are defined when there is a
2753 
+   specific action that a client can take based upon the additional
2754 
+   information.
2755 
+
2756 
+   The currently defined response codes are:
2757 
+
2758 
+      ALERT          The human-readable text contains a special alert
2759 
+                     that MUST be presented to the user in a fashion
2760 
+                     that calls the user's attention to the message.
2761 
+
2762 
+      NEWNAME        Followed by a mailbox name and a new mailbox name.
2763 
+                     A SELECT or EXAMINE is failing because the target
2764 
+                     mailbox name no longer exists because it was
2765 
+                     renamed to the new mailbox name.  This is a hint to
2766 
+                     the client that the operation can succeed if the
2767 
+                     SELECT or EXAMINE is reissued with the new mailbox
2768 
+                     name.
2769 
+
2770 
+      PARSE          The human-readable text represents an error in
2771 
+                     parsing the [RFC-822] header or [MIME-IMB] headers
2772 
+                     of a message in the mailbox.
2773 
+
2774 
+      PERMANENTFLAGS Followed by a parenthesized list of flags,
2775 
+                     indicates which of the known flags that the client
2776 
+                     can change permanently.  Any flags that are in the
2777 
+                     FLAGS untagged response, but not the PERMANENTFLAGS
2778 
+                     list, can not be set permanently.  If the client
2779 
+                     attempts to STORE a flag that is not in the
2780 
+                     PERMANENTFLAGS list, the server will either reject
2781 
+                     it with a NO reply or store the state for the
2782 
+                     remainder of the current session only.  The
2783 
+                     PERMANENTFLAGS list can also include the special
2784 
+                     flag \*, which indicates that it is possible to
2785 
+                     create new keywords by attempting to store those
2786 
+                     flags in the mailbox.
2787 
+
2788 
+      READ-ONLY      The mailbox is selected read-only, or its access
2789 
+                     while selected has changed from read-write to
2790 
+                     read-only.
2791 
+
2792 
+      READ-WRITE     The mailbox is selected read-write, or its access
2793 
+                     while selected has changed from read-only to
2794 
+                     read-write.
2795 
+
2796 
+
2797 
+
2798 
+
2799 
+
2800 
+
2801 
+
2802 
+Crispin                     Standards Track                    [Page 50]
2803 
+
2804 
+RFC 2060                       IMAP4rev1                   December 1996
2805 
+
2806 
+
2807 
+      TRYCREATE      An APPEND or COPY attempt is failing because the
2808 
+                     target mailbox does not exist (as opposed to some
2809 
+                     other reason).  This is a hint to the client that
2810 
+                     the operation can succeed if the mailbox is first
2811 
+                     created by the CREATE command.
2812 
+
2813 
+      UIDVALIDITY    Followed by a decimal number, indicates the unique
2814 
+                     identifier validity value.
2815 
+
2816 
+      UNSEEN         Followed by a decimal number, indicates the number
2817 
+                     of the first message without the \Seen flag set.
2818 
+
2819 
+      Additional response codes defined by particular client or server
2820 
+      implementations SHOULD be prefixed with an "X" until they are
2821 
+      added to a revision of this protocol.  Client implementations
2822 
+      SHOULD ignore response codes that they do not recognize.
2823 
+
2824 
+7.1.1.  OK Response
2825 
+
2826 
+   Contents:   OPTIONAL response code
2827 
+               human-readable text
2828 
+
2829 
+      The OK response indicates an information message from the server.
2830 
+      When tagged, it indicates successful completion of the associated
2831 
+      command.  The human-readable text MAY be presented to the user as
2832 
+      an information message.  The untagged form indicates an
2833 
+      information-only message; the nature of the information MAY be
2834 
+      indicated by a response code.
2835 
+
2836 
+      The untagged form is also used as one of three possible greetings
2837 
+      at connection startup.  It indicates that the connection is not
2838 
+      yet authenticated and that a LOGIN command is needed.
2839 
+
2840 
+   Example:    S: * OK IMAP4rev1 server ready
2841 
+               C: A001 LOGIN fred blurdybloop
2842 
+               S: * OK [ALERT] System shutdown in 10 minutes
2843 
+               S: A001 OK LOGIN Completed
2844 
+
2845 
+7.1.2.  NO Response
2846 
+
2847 
+      Contents:   OPTIONAL response code
2848 
+                  human-readable text
2849 
+
2850 
+      The NO response indicates an operational error message from the
2851 
+      server.  When tagged, it indicates unsuccessful completion of the
2852 
+      associated command.  The untagged form indicates a warning; the
2853 
+      command can still complete successfully.  The human-readable text
2854 
+      describes the condition.
2855 
+
2856 
+
2857 
+
2858 
+Crispin                     Standards Track                    [Page 51]
2859 
+
2860 
+RFC 2060                       IMAP4rev1                   December 1996
2861 
+
2862 
+
2863 
+   Example:    C: A222 COPY 1:2 owatagusiam
2864 
+               S: * NO Disk is 98% full, please delete unnecessary data
2865 
+               S: A222 OK COPY completed
2866 
+               C: A223 COPY 3:200 blurdybloop
2867 
+               S: * NO Disk is 98% full, please delete unnecessary data
2868 
+               S: * NO Disk is 99% full, please delete unnecessary data
2869 
+               S: A223 NO COPY failed: disk is full
2870 
+
2871 
+7.1.3.  BAD Response
2872 
+
2873 
+   Contents:   OPTIONAL response code
2874 
+               human-readable text
2875 
+
2876 
+      The BAD response indicates an error message from the server.  When
2877 
+      tagged, it reports a protocol-level error in the client's command;
2878 
+      the tag indicates the command that caused the error.  The untagged
2879 
+      form indicates a protocol-level error for which the associated
2880 
+      command can not be determined; it can also indicate an internal
2881 
+      server failure.  The human-readable text describes the condition.
2882 
+
2883 
+   Example:    C: ...very long command line...
2884 
+               S: * BAD Command line too long
2885 
+               C: ...empty line...
2886 
+               S: * BAD Empty command line
2887 
+               C: A443 EXPUNGE
2888 
+               S: * BAD Disk crash, attempting salvage to a new disk!
2889 
+               S: * OK Salvage successful, no data lost
2890 
+               S: A443 OK Expunge completed
2891 
+
2892 
+7.1.4.  PREAUTH Response
2893 
+
2894 
+   Contents:   OPTIONAL response code
2895 
+               human-readable text
2896 
+
2897 
+      The PREAUTH response is always untagged, and is one of three
2898 
+      possible greetings at connection startup.  It indicates that the
2899 
+      connection has already been authenticated by external means and
2900 
+      thus no LOGIN command is needed.
2901 
+
2902 
+   Example:    S: * PREAUTH IMAP4rev1 server logged in as Smith
2903 
+
2904 
+7.1.5.  BYE Response
2905 
+
2906 
+   Contents:   OPTIONAL response code
2907 
+               human-readable text
2908 
+
2909 
+
2910 
+
2911 
+
2912 
+
2913 
+
2914 
+Crispin                     Standards Track                    [Page 52]
2915 
+
2916 
+RFC 2060                       IMAP4rev1                   December 1996
2917 
+
2918 
+
2919 
+      The BYE response is always untagged, and indicates that the server
2920 
+      is about to close the connection.  The human-readable text MAY be
2921 
+      displayed to the user in a status report by the client.  The BYE
2922 
+      response is sent under one of four conditions:
2923 
+
2924 
+         1) as part of a normal logout sequence.  The server will close
2925 
+            the connection after sending the tagged OK response to the
2926 
+            LOGOUT command.
2927 
+
2928 
+         2) as a panic shutdown announcement.  The server closes the
2929 
+            connection immediately.
2930 
+
2931 
+         3) as an announcement of an inactivity autologout.  The server
2932 
+            closes the connection immediately.
2933 
+
2934 
+         4) as one of three possible greetings at connection startup,
2935 
+            indicating that the server is not willing to accept a
2936 
+            connection from this client.  The server closes the
2937 
+            connection immediately.
2938 
+
2939 
+      The difference between a BYE that occurs as part of a normal
2940 
+      LOGOUT sequence (the first case) and a BYE that occurs because of
2941 
+      a failure (the other three cases) is that the connection closes
2942 
+      immediately in the failure case.
2943 
+
2944 
+   Example:    S: * BYE Autologout; idle for too long
2945 
+
2946 
+7.2.    Server Responses - Server and Mailbox Status
2947 
+
2948 
+   These responses are always untagged.  This is how server and mailbox
2949 
+   status data are transmitted from the server to the client.  Many of
2950 
+   these responses typically result from a command with the same name.
2951 
+
2952 
+7.2.1.  CAPABILITY Response
2953 
+
2954 
+   Contents:   capability listing
2955 
+
2956 
+      The CAPABILITY response occurs as a result of a CAPABILITY
2957 
+      command.  The capability listing contains a space-separated
2958 
+      listing of capability names that the server supports.  The
2959 
+      capability listing MUST include the atom "IMAP4rev1".
2960 
+
2961 
+      A capability name which begins with "AUTH=" indicates that the
2962 
+      server supports that particular authentication mechanism.
2963 
+
2964 
+
2965 
+
2966 
+
2967 
+
2968 
+
2969 
+
2970 
+Crispin                     Standards Track                    [Page 53]
2971 
+
2972 
+RFC 2060                       IMAP4rev1                   December 1996
2973 
+
2974 
+
2975 
+      Other capability names indicate that the server supports an
2976 
+      extension, revision, or amendment to the IMAP4rev1 protocol.
2977 
+      Server responses MUST conform to this document until the client
2978 
+      issues a command that uses the associated capability.
2979 
+
2980 
+      Capability names MUST either begin with "X" or be standard or
2981 
+      standards-track IMAP4rev1 extensions, revisions, or amendments
2982 
+      registered with IANA.  A server MUST NOT offer unregistered or
2983 
+      non-standard capability names, unless such names are prefixed with
2984 
+      an "X".
2985 
+
2986 
+      Client implementations SHOULD NOT require any capability name
2987 
+      other than "IMAP4rev1", and MUST ignore any unknown capability
2988 
+      names.
2989 
+
2990 
+   Example:    S: * CAPABILITY IMAP4rev1 AUTH=KERBEROS_V4 XPIG-LATIN
2991 
+
2992 
+7.2.2.  LIST Response
2993 
+
2994 
+   Contents:   name attributes
2995 
+               hierarchy delimiter
2996 
+               name
2997 
+
2998 
+      The LIST response occurs as a result of a LIST command.  It
2999 
+      returns a single name that matches the LIST specification.  There
3000 
+      can be multiple LIST responses for a single LIST command.
3001 
+
3002 
+      Four name attributes are defined:
3003 
+
3004 
+      \Noinferiors   It is not possible for any child levels of
3005 
+                     hierarchy to exist under this name; no child levels
3006 
+                     exist now and none can be created in the future.
3007 
+
3008 
+      \Noselect      It is not possible to use this name as a selectable
3009 
+                     mailbox.
3010 
+
3011 
+      \Marked        The mailbox has been marked "interesting" by the
3012 
+                     server; the mailbox probably contains messages that
3013 
+                     have been added since the last time the mailbox was
3014 
+                     selected.
3015 
+
3016 
+      \Unmarked      The mailbox does not contain any additional
3017 
+                     messages since the last time the mailbox was
3018 
+                     selected.
3019 
+
3020 
+      If it is not feasible for the server to determine whether the
3021 
+      mailbox is "interesting" or not, or if the name is a \Noselect
3022 
+      name, the server SHOULD NOT send either \Marked or \Unmarked.
3023 
+
3024 
+
3025 
+
3026 
+Crispin                     Standards Track                    [Page 54]
3027 
+
3028 
+RFC 2060                       IMAP4rev1                   December 1996
3029 
+
3030 
+
3031 
+      The hierarchy delimiter is a character used to delimit levels of
3032 
+      hierarchy in a mailbox name.  A client can use it to create child
3033 
+      mailboxes, and to search higher or lower levels of naming
3034 
+      hierarchy.  All children of a top-level hierarchy node MUST use
3035 
+      the same separator character.  A NIL hierarchy delimiter means
3036 
+      that no hierarchy exists; the name is a "flat" name.
3037 
+
3038 
+      The name represents an unambiguous left-to-right hierarchy, and
3039 
+      MUST be valid for use as a reference in LIST and LSUB commands.
3040 
+      Unless \Noselect is indicated, the name MUST also be valid as an
3041 
+            argument for commands, such as SELECT, that accept mailbox
3042 
+      names.
3043 
+
3044 
+   Example:    S: * LIST (\Noselect) "/" ~/Mail/foo
3045 
+
3046 
+7.2.3.  LSUB Response
3047 
+
3048 
+   Contents:   name attributes
3049 
+               hierarchy delimiter
3050 
+               name
3051 
+
3052 
+      The LSUB response occurs as a result of an LSUB command.  It
3053 
+      returns a single name that matches the LSUB specification.  There
3054 
+      can be multiple LSUB responses for a single LSUB command.  The
3055 
+      data is identical in format to the LIST response.
3056 
+
3057 
+   Example:    S: * LSUB () "." #news.comp.mail.misc
3058 
+
3059 
+7.2.4   STATUS Response
3060 
+
3061 
+   Contents:   name
3062 
+               status parenthesized list
3063 
+
3064 
+      The STATUS response occurs as a result of an STATUS command.  It
3065 
+      returns the mailbox name that matches the STATUS specification and
3066 
+      the requested mailbox status information.
3067 
+
3068 
+   Example:    S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292)
3069 
+
3070 
+7.2.5.  SEARCH Response
3071 
+
3072 
+   Contents:   zero or more numbers
3073 
+
3074 
+
3075 
+
3076 
+
3077 
+
3078 
+
3079 
+
3080 
+
3081 
+
3082 
+Crispin                     Standards Track                    [Page 55]
3083 
+
3084 
+RFC 2060                       IMAP4rev1                   December 1996
3085 
+
3086 
+
3087 
+      The SEARCH response occurs as a result of a SEARCH or UID SEARCH
3088 
+      command.  The number(s) refer to those messages that match the
3089 
+      search criteria.  For SEARCH, these are message sequence numbers;
3090 
+      for UID SEARCH, these are unique identifiers.  Each number is
3091 
+      delimited by a space.
3092 
+
3093 
+   Example:    S: * SEARCH 2 3 6
3094 
+
3095 
+7.2.6.  FLAGS Response
3096 
+
3097 
+   Contents:   flag parenthesized list
3098 
+
3099 
+      The FLAGS response occurs as a result of a SELECT or EXAMINE
3100 
+      command.  The flag parenthesized list identifies the flags (at a
3101 
+      minimum, the system-defined flags) that are applicable for this
3102 
+      mailbox.  Flags other than the system flags can also exist,
3103 
+      depending on server implementation.
3104 
+
3105 
+      The update from the FLAGS response MUST be recorded by the client.
3106 
+
3107 
+   Example:    S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
3108 
+
3109 
+7.3.    Server Responses - Mailbox Size
3110 
+
3111 
+   These responses are always untagged.  This is how changes in the size
3112 
+   of the mailbox are trasnmitted from the server to the client.
3113 
+   Immediately following the "*" token is a number that represents a
3114 
+   message count.
3115 
+
3116 
+7.3.1.  EXISTS Response
3117 
+
3118 
+   Contents:   none
3119 
+
3120 
+      The EXISTS response reports the number of messages in the mailbox.
3121 
+      This response occurs as a result of a SELECT or EXAMINE command,
3122 
+      and if the size of the mailbox changes (e.g. new mail).
3123 
+
3124 
+      The update from the EXISTS response MUST be recorded by the
3125 
+      client.
3126 
+
3127 
+   Example:    S: * 23 EXISTS
3128 
+
3129 
+
3130 
+
3131 
+
3132 
+
3133 
+
3134 
+
3135 
+
3136 
+
3137 
+
3138 
+Crispin                     Standards Track                    [Page 56]
3139 
+
3140 
+RFC 2060                       IMAP4rev1                   December 1996
3141 
+
3142 
+
3143 
+7.3.2.  RECENT Response
3144 
+
3145 
+      Contents:   none
3146 
+
3147 
+      The RECENT response reports the number of messages with the
3148 
+      \Recent flag set.  This response occurs as a result of a SELECT or
3149 
+      EXAMINE command, and if the size of the mailbox changes (e.g. new
3150 
+      mail).
3151 
+
3152 
+         Note: It is not guaranteed that the message sequence numbers of
3153 
+         recent messages will be a contiguous range of the highest n
3154 
+         messages in the mailbox (where n is the value reported by the
3155 
+         RECENT response).  Examples of situations in which this is not
3156 
+         the case are: multiple clients having the same mailbox open
3157 
+         (the first session to be notified will see it as recent, others
3158 
+         will probably see it as non-recent), and when the mailbox is
3159 
+         re-ordered by a non-IMAP agent.
3160 
+
3161 
+         The only reliable way to identify recent messages is to look at
3162 
+         message flags to see which have the \Recent flag set, or to do
3163 
+         a SEARCH RECENT.
3164 
+
3165 
+         The update from the RECENT response MUST be recorded by the
3166 
+         client.
3167 
+
3168 
+   Example:    S: * 5 RECENT
3169 
+
3170 
+7.4.    Server Responses - Message Status
3171 
+
3172 
+   These responses are always untagged.  This is how message data are
3173 
+   transmitted from the server to the client, often as a result of a
3174 
+   command with the same name.  Immediately following the "*" token is a
3175 
+   number that represents a message sequence number.
3176 
+
3177 
+7.4.1.  EXPUNGE Response
3178 
+
3179 
+   Contents:   none
3180 
+
3181 
+      The EXPUNGE response reports that the specified message sequence
3182 
+      number has been permanently removed from the mailbox.  The message
3183 
+      sequence number for each successive message in the mailbox is
3184 
+      immediately decremented by 1, and this decrement is reflected in
3185 
+      message sequence numbers in subsequent responses (including other
3186 
+      untagged EXPUNGE responses).
3187 
+
3188 
+      As a result of the immediate decrement rule, message sequence
3189 
+      numbers that appear in a set of successive EXPUNGE responses
3190 
+      depend upon whether the messages are removed starting from lower
3191 
+
3192 
+
3193 
+
3194 
+Crispin                     Standards Track                    [Page 57]
3195 
+
3196 
+RFC 2060                       IMAP4rev1                   December 1996
3197 
+
3198 
+
3199 
+      numbers to higher numbers, or from higher numbers to lower
3200 
+      numbers.  For example, if the last 5 messages in a 9-message
3201 
+      mailbox are expunged; a "lower to higher" server will send five
3202 
+      untagged EXPUNGE responses for message sequence number 5, whereas
3203 
+      a "higher to lower server" will send successive untagged EXPUNGE
3204 
+      responses for message sequence numbers 9, 8, 7, 6, and 5.
3205 
+
3206 
+      An EXPUNGE response MUST NOT be sent when no command is in
3207 
+      progress; nor while responding to a FETCH, STORE, or SEARCH
3208 
+      command.  This rule is necessary to prevent a loss of
3209 
+      synchronization of message sequence numbers between client and
3210 
+      server.
3211 
+
3212 
+      The update from the EXPUNGE response MUST be recorded by the
3213 
+      client.
3214 
+
3215 
+   Example:    S: * 44 EXPUNGE
3216 
+
3217 
+7.4.2.  FETCH Response
3218 
+
3219 
+   Contents:   message data
3220 
+
3221 
+      The FETCH response returns data about a message to the client.
3222 
+      The data are pairs of data item names and their values in
3223 
+      parentheses.  This response occurs as the result of a FETCH or
3224 
+      STORE command, as well as by unilateral server decision (e.g. flag
3225 
+      updates).
3226 
+
3227 
+      The current data items are:
3228 
+
3229 
+      BODY           A form of BODYSTRUCTURE without extension data.
3230 
+
3231 
+      BODY[<section>]<<origin_octet>>
3232 
+                     A string expressing the body contents of the
3233 
+                     specified section.  The string SHOULD be
3234 
+                     interpreted by the client according to the content
3235 
+                     transfer encoding, body type, and subtype.
3236 
+
3237 
+                     If the origin octet is specified, this string is a
3238 
+                     substring of the entire body contents, starting at
3239 
+                     that origin octet.  This means that BODY[]<0> MAY
3240 
+                     be truncated, but BODY[] is NEVER truncated.
3241 
+
3242 
+                     8-bit textual data is permitted if a [CHARSET]
3243 
+                     identifier is part of the body parameter
3244 
+                     parenthesized list for this section.  Note that
3245 
+                     headers (part specifiers HEADER or MIME, or the
3246 
+                     header portion of a MESSAGE/RFC822 part), MUST be
3247 
+
3248 
+
3249 
+
3250 
+Crispin                     Standards Track                    [Page 58]
3251 
+
3252 
+RFC 2060                       IMAP4rev1                   December 1996
3253 
+
3254 
+
3255 
+                     7-bit; 8-bit characters are not permitted in
3256 
+                     headers.  Note also that the blank line at the end
3257 
+                     of the header is always included in header data.
3258 
+
3259 
+                     Non-textual data such as binary data MUST be
3260 
+                     transfer encoded into a textual form such as BASE64
3261 
+                     prior to being sent to the client.  To derive the
3262 
+                     original binary data, the client MUST decode the
3263 
+                     transfer encoded string.
3264 
+
3265 
+      BODYSTRUCTURE  A parenthesized list that describes the [MIME-IMB]
3266 
+                     body structure of a message.  This is computed by
3267 
+                     the server by parsing the [MIME-IMB] header fields,
3268 
+                     defaulting various fields as necessary.
3269 
+
3270 
+                     For example, a simple text message of 48 lines and
3271 
+                     2279 octets can have a body structure of: ("TEXT"
3272 
+                     "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 2279
3273 
+                     48)
3274 
+
3275 
+                     Multiple parts are indicated by parenthesis
3276 
+                     nesting.  Instead of a body type as the first
3277 
+                     element of the parenthesized list there is a nested
3278 
+                     body.  The second element of the parenthesized list
3279 
+                     is the multipart subtype (mixed, digest, parallel,
3280 
+                     alternative, etc.).
3281 
+
3282 
+                     For example, a two part message consisting of a
3283 
+                     text and a BASE645-encoded text attachment can have
3284 
+                     a body structure of: (("TEXT" "PLAIN" ("CHARSET"
3285 
+                     "US-ASCII") NIL NIL "7BIT" 1152 23)("TEXT" "PLAIN"
3286 
+                     ("CHARSET" "US-ASCII" "NAME" "cc.diff")
3287 
+                     "<960723163407.20117h@cac.washington.edu>"
3288 
+                     "Compiler diff" "BASE64" 4554 73) "MIXED"))
3289 
+
3290 
+                     Extension data follows the multipart subtype.
3291 
+                     Extension data is never returned with the BODY
3292 
+                     fetch, but can be returned with a BODYSTRUCTURE
3293 
+                     fetch.  Extension data, if present, MUST be in the
3294 
+                     defined order.
3295 
+
3296 
+                     The extension data of a multipart body part are in
3297 
+                     the following order:
3298 
+
3299 
+                     body parameter parenthesized list
3300 
+                        A parenthesized list of attribute/value pairs
3301 
+                        [e.g. ("foo" "bar" "baz" "rag") where "bar" is
3302 
+                        the value of "foo" and "rag" is the value of
3303 
+
3304 
+
3305 
+
3306 
+Crispin                     Standards Track                    [Page 59]
3307 
+
3308 
+RFC 2060                       IMAP4rev1                   December 1996
3309 
+
3310 
+
3311 
+                        "baz"] as defined in [MIME-IMB].
3312 
+
3313 
+                     body disposition
3314 
+                        A parenthesized list, consisting of a
3315 
+                        disposition type string followed by a
3316 
+                        parenthesized list of disposition
3317 
+                        attribute/value pairs.  The disposition type and
3318 
+                        attribute names will be defined in a future
3319 
+                        standards-track revision to [DISPOSITION].
3320 
+
3321 
+                     body language
3322 
+                        A string or parenthesized list giving the body
3323 
+                        language value as defined in [LANGUAGE-TAGS].
3324 
+
3325 
+                     Any following extension data are not yet defined in
3326 
+                     this version of the protocol.  Such extension data
3327 
+                     can consist of zero or more NILs, strings, numbers,
3328 
+                     or potentially nested parenthesized lists of such
3329 
+                     data.  Client implementations that do a
3330 
+                     BODYSTRUCTURE fetch MUST be prepared to accept such
3331 
+                     extension data.  Server implementations MUST NOT
3332 
+                     send such extension data until it has been defined
3333 
+                     by a revision of this protocol.
3334 
+
3335 
+                     The basic fields of a non-multipart body part are
3336 
+                     in the following order:
3337 
+
3338 
+                     body type
3339 
+                        A string giving the content media type name as
3340 
+                        defined in [MIME-IMB].
3341 
+
3342 
+                     body subtype
3343 
+                        A string giving the content subtype name as
3344 
+                        defined in [MIME-IMB].
3345 
+
3346 
+                     body parameter parenthesized list
3347 
+                        A parenthesized list of attribute/value pairs
3348 
+                        [e.g. ("foo" "bar" "baz" "rag") where "bar" is
3349 
+                        the value of "foo" and "rag" is the value of
3350 
+                        "baz"] as defined in [MIME-IMB].
3351 
+
3352 
+                     body id
3353 
+                        A string giving the content id as defined in
3354 
+                        [MIME-IMB].
3355 
+
3356 
+                     body description
3357 
+                        A string giving the content description as
3358 
+                        defined in [MIME-IMB].
3359 
+
3360 
+
3361 
+
3362 
+Crispin                     Standards Track                    [Page 60]
3363 
+
3364 
+RFC 2060                       IMAP4rev1                   December 1996
3365 
+
3366 
+
3367 
+                     body encoding
3368 
+                        A string giving the content transfer encoding as
3369 
+                        defined in [MIME-IMB].
3370 
+
3371 
+                     body size
3372 
+                        A number giving the size of the body in octets.
3373 
+                        Note that this size is the size in its transfer
3374 
+                        encoding and not the resulting size after any
3375 
+                        decoding.
3376 
+
3377 
+                     A body type of type MESSAGE and subtype RFC822
3378 
+                     contains, immediately after the basic fields, the
3379 
+                     envelope structure, body structure, and size in
3380 
+                     text lines of the encapsulated message.
3381 
+
3382 
+                     A body type of type TEXT contains, immediately
3383 
+                     after the basic fields, the size of the body in
3384 
+                     text lines.  Note that this size is the size in its
3385 
+                     content transfer encoding and not the resulting
3386 
+                     size after any decoding.
3387 
+
3388 
+                     Extension data follows the basic fields and the
3389 
+                     type-specific fields listed above.  Extension data
3390 
+                     is never returned with the BODY fetch, but can be
3391 
+                     returned with a BODYSTRUCTURE fetch.  Extension
3392 
+                     data, if present, MUST be in the defined order.
3393 
+
3394 
+                     The extension data of a non-multipart body part are
3395 
+                     in the following order:
3396 
+
3397 
+                     body MD5
3398 
+                        A string giving the body MD5 value as defined in
3399 
+                        [MD5].
3400 
+
3401 
+                     body disposition
3402 
+                        A parenthesized list with the same content and
3403 
+                        function as the body disposition for a multipart
3404 
+                        body part.
3405 
+
3406 
+                     body language
3407 
+                        A string or parenthesized list giving the body
3408 
+                        language value as defined in [LANGUAGE-TAGS].
3409 
+
3410 
+                     Any following extension data are not yet defined in
3411 
+                     this version of the protocol, and would be as
3412 
+                     described above under multipart extension data.
3413 
+
3414 
+
3415 
+
3416 
+
3417 
+
3418 
+Crispin                     Standards Track                    [Page 61]
3419 
+
3420 
+RFC 2060                       IMAP4rev1                   December 1996
3421 
+
3422 
+
3423 
+      ENVELOPE       A parenthesized list that describes the envelope
3424 
+                     structure of a message.  This is computed by the
3425 
+                     server by parsing the [RFC-822] header into the
3426 
+                     component parts, defaulting various fields as
3427 
+                     necessary.
3428 
+
3429 
+                     The fields of the envelope structure are in the
3430 
+                     following order: date, subject, from, sender,
3431 
+                     reply-to, to, cc, bcc, in-reply-to, and message-id.
3432 
+                     The date, subject, in-reply-to, and message-id
3433 
+                     fields are strings.  The from, sender, reply-to,
3434 
+                     to, cc, and bcc fields are parenthesized lists of
3435 
+                     address structures.
3436 
+
3437 
+                     An address structure is a parenthesized list that
3438 
+                     describes an electronic mail address.  The fields
3439 
+                     of an address structure are in the following order:
3440 
+                     personal name, [SMTP] at-domain-list (source
3441 
+                     route), mailbox name, and host name.
3442 
+
3443 
+                     [RFC-822] group syntax is indicated by a special
3444 
+                     form of address structure in which the host name
3445 
+                     field is NIL.  If the mailbox name field is also
3446 
+                     NIL, this is an end of group marker (semi-colon in
3447 
+                     RFC 822 syntax).  If the mailbox name field is
3448 
+                     non-NIL, this is a start of group marker, and the
3449 
+                     mailbox name field holds the group name phrase.
3450 
+
3451 
+                     Any field of an envelope or address structure that
3452 
+                     is not applicable is presented as NIL.  Note that
3453 
+                     the server MUST default the reply-to and sender
3454 
+                     fields from the from field; a client is not
3455 
+                     expected to know to do this.
3456 
+
3457 
+      FLAGS          A parenthesized list of flags that are set for this
3458 
+                     message.
3459 
+
3460 
+      INTERNALDATE   A string representing the internal date of the
3461 
+                     message.
3462 
+
3463 
+      RFC822         Equivalent to BODY[].
3464 
+
3465 
+      RFC822.HEADER  Equivalent to BODY.PEEK[HEADER].
3466 
+
3467 
+      RFC822.SIZE    A number expressing the [RFC-822] size of the
3468 
+                     message.
3469 
+
3470 
+      RFC822.TEXT    Equivalent to BODY[TEXT].
3471 
+
3472 
+
3473 
+
3474 
+Crispin                     Standards Track                    [Page 62]
3475 
+
3476 
+RFC 2060                       IMAP4rev1                   December 1996
3477 
+
3478 
+
3479 
+      UID            A number expressing the unique identifier of the
3480 
+                     message.
3481 
+
3482 
+
3483 
+   Example:    S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827)
3484 
+
3485 
+7.5.    Server Responses - Command Continuation Request
3486 
+
3487 
+   The command continuation request response is indicated by a "+" token
3488 
+   instead of a tag.  This form of response indicates that the server is
3489 
+   ready to accept the continuation of a command from the client.  The
3490 
+   remainder of this response is a line of text.
3491 
+
3492 
+   This response is used in the AUTHORIZATION command to transmit server
3493 
+   data to the client, and request additional client data.  This
3494 
+   response is also used if an argument to any command is a literal.
3495 
+
3496 
+   The client is not permitted to send the octets of the literal unless
3497 
+   the server indicates that it expects it.  This permits the server to
3498 
+   process commands and reject errors on a line-by-line basis.  The
3499 
+   remainder of the command, including the CRLF that terminates a
3500 
+   command, follows the octets of the literal.  If there are any
3501 
+   additional command arguments the literal octets are followed by a
3502 
+   space and those arguments.
3503 
+
3504 
+   Example:    C: A001 LOGIN {11}
3505 
+               S: + Ready for additional command text
3506 
+               C: FRED FOOBAR {7}
3507 
+               S: + Ready for additional command text
3508 
+               C: fat man
3509 
+               S: A001 OK LOGIN completed
3510 
+               C: A044 BLURDYBLOOP {102856}
3511 
+               S: A044 BAD No such command as "BLURDYBLOOP"
3512 
+
3513 
+8.      Sample IMAP4rev1 connection
3514 
+
3515 
+   The following is a transcript of an IMAP4rev1 connection.  A long
3516 
+   line in this sample is broken for editorial clarity.
3517 
+
3518 
+S:   * OK IMAP4rev1 Service Ready
3519 
+C:   a001 login mrc secret
3520 
+S:   a001 OK LOGIN completed
3521 
+C:   a002 select inbox
3522 
+S:   * 18 EXISTS
3523 
+S:   * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
3524 
+S:   * 2 RECENT
3525 
+S:   * OK [UNSEEN 17] Message 17 is the first unseen message
3526 
+S:   * OK [UIDVALIDITY 3857529045] UIDs valid
3527 
+
3528 
+
3529 
+
3530 
+Crispin                     Standards Track                    [Page 63]
3531 
+
3532 
+RFC 2060                       IMAP4rev1                   December 1996
3533 
+
3534 
+
3535 
+S:   a002 OK [READ-WRITE] SELECT completed
3536 
+C:   a003 fetch 12 full
3537 
+S:   * 12 FETCH (FLAGS (\Seen) INTERNALDATE "17-Jul-1996 02:44:25 -0700"
3538 
+      RFC822.SIZE 4286 ENVELOPE ("Wed, 17 Jul 1996 02:23:25 -0700 (PDT)"
3539 
+      "IMAP4rev1 WG mtg summary and minutes"
3540 
+      (("Terry Gray" NIL "gray" "cac.washington.edu"))
3541 
+      (("Terry Gray" NIL "gray" "cac.washington.edu"))
3542 
+      (("Terry Gray" NIL "gray" "cac.washington.edu"))
3543 
+      ((NIL NIL "imap" "cac.washington.edu"))
3544 
+      ((NIL NIL "minutes" "CNRI.Reston.VA.US")
3545 
+      ("John Klensin" NIL "KLENSIN" "INFOODS.MIT.EDU")) NIL NIL
3546 
+      "<B27397-0100000@cac.washington.edu>")
3547 
+       BODY ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 3028 92))
3548 
+S:    a003 OK FETCH completed
3549 
+C:    a004 fetch 12 body[header]
3550 
+S:    * 12 FETCH (BODY[HEADER] {350}
3551 
+S:    Date: Wed, 17 Jul 1996 02:23:25 -0700 (PDT)
3552 
+S:    From: Terry Gray <gray@cac.washington.edu>
3553 
+S:    Subject: IMAP4rev1 WG mtg summary and minutes
3554 
+S:    To: imap@cac.washington.edu
3555 
+S:    cc: minutes@CNRI.Reston.VA.US, John Klensin <KLENSIN@INFOODS.MIT.EDU>
3556 
+S:    Message-Id: <B27397-0100000@cac.washington.edu>
3557 
+S:    MIME-Version: 1.0
3558 
+S:    Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
3559 
+S:
3560 
+S:    )
3561 
+S:    a004 OK FETCH completed
3562 
+C:    a005 store 12 +flags \deleted
3563 
+S:    * 12 FETCH (FLAGS (\Seen \Deleted))
3564 
+S:    a005 OK +FLAGS completed
3565 
+C:    a006 logout
3566 
+S:    * BYE IMAP4rev1 server terminating connection
3567 
+S:    a006 OK LOGOUT completed
3568 
+
3569 
+9.      Formal Syntax
3570 
+
3571 
+   The following syntax specification uses the augmented Backus-Naur
3572 
+   Form (BNF) notation as specified in [RFC-822] with one exception; the
3573 
+   delimiter used with the "#" construct is a single space (SPACE) and
3574 
+   not one or more commas.
3575 
+
3576 
+   In the case of alternative or optional rules in which a later rule
3577 
+   overlaps an earlier rule, the rule which is listed earlier MUST take
3578 
+   priority.  For example, "\Seen" when parsed as a flag is the \Seen
3579 
+   flag name and not a flag_extension, even though "\Seen" could be
3580 
+   parsed as a flag_extension.  Some, but not all, instances of this
3581 
+   rule are noted below.
3582 
+
3583 
+
3584 
+
3585 
+
3586 
+Crispin                     Standards Track                    [Page 64]
3587 
+
3588 
+RFC 2060                       IMAP4rev1                   December 1996
3589 
+
3590 
+
3591 
+   Except as noted otherwise, all alphabetic characters are case-
3592 
+   insensitive.  The use of upper or lower case characters to define
3593 
+   token strings is for editorial clarity only.  Implementations MUST
3594 
+   accept these strings in a case-insensitive fashion.
3595 
+
3596 
+address         ::= "(" addr_name SPACE addr_adl SPACE addr_mailbox
3597 
+                    SPACE addr_host ")"
3598 
+
3599 
+addr_adl        ::= nstring
3600 
+                    ;; Holds route from [RFC-822] route-addr if
3601 
+                    ;; non-NIL
3602 
+
3603 
+addr_host       ::= nstring
3604 
+                    ;; NIL indicates [RFC-822] group syntax.
3605 
+                    ;; Otherwise, holds [RFC-822] domain name
3606 
+
3607 
+addr_mailbox    ::= nstring
3608 
+                    ;; NIL indicates end of [RFC-822] group; if
3609 
+                    ;; non-NIL and addr_host is NIL, holds
3610 
+                    ;; [RFC-822] group name.
3611 
+                    ;; Otherwise, holds [RFC-822] local-part
3612 
+
3613 
+addr_name       ::= nstring
3614 
+                    ;; Holds phrase from [RFC-822] mailbox if
3615 
+                    ;; non-NIL
3616 
+
3617 
+alpha           ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" /
3618 
+                    "I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" /
3619 
+                    "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" /
3620 
+                    "Y" / "Z" /
3621 
+                    "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" /
3622 
+                    "i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" /
3623 
+                    "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" /
3624 
+                    "y" / "z"
3625 
+                    ;; Case-sensitive
3626 
+
3627 
+append          ::= "APPEND" SPACE mailbox [SPACE flag_list]
3628 
+                    [SPACE date_time] SPACE literal
3629 
+
3630 
+astring         ::= atom / string
3631 
+
3632 
+atom            ::= 1*ATOM_CHAR
3633 
+
3634 
+ATOM_CHAR       ::= <any CHAR except atom_specials>
3635 
+
3636 
+atom_specials   ::= "(" / ")" / "{" / SPACE / CTL / list_wildcards /
3637 
+                    quoted_specials
3638 
+
3639 
+
3640 
+
3641 
+
3642 
+Crispin                     Standards Track                    [Page 65]
3643 
+
3644 
+RFC 2060                       IMAP4rev1                   December 1996
3645 
+
3646 
+
3647 
+authenticate    ::= "AUTHENTICATE" SPACE auth_type *(CRLF base64)
3648 
+
3649 
+auth_type       ::= atom
3650 
+                    ;; Defined by [IMAP-AUTH]
3651 
+
3652 
+base64          ::= *(4base64_char) [base64_terminal]
3653 
+
3654 
+base64_char     ::= alpha / digit / "+" / "/"
3655 
+
3656 
+base64_terminal ::= (2base64_char "==") / (3base64_char "=")
3657 
+
3658 
+body            ::= "(" body_type_1part / body_type_mpart ")"
3659 
+
3660 
+body_extension  ::= nstring / number / "(" 1#body_extension ")"
3661 
+                    ;; Future expansion.  Client implementations
3662 
+                    ;; MUST accept body_extension fields.  Server
3663 
+                    ;; implementations MUST NOT generate
3664 
+                    ;; body_extension fields except as defined by
3665 
+                    ;; future standard or standards-track
3666 
+                    ;; revisions of this specification.
3667 
+
3668 
+body_ext_1part  ::= body_fld_md5 [SPACE body_fld_dsp
3669 
+                    [SPACE body_fld_lang
3670 
+                    [SPACE 1#body_extension]]]
3671 
+                    ;; MUST NOT be returned on non-extensible
3672 
+                    ;; "BODY" fetch
3673 
+
3674 
+body_ext_mpart  ::= body_fld_param
3675 
+                    [SPACE body_fld_dsp SPACE body_fld_lang
3676 
+                    [SPACE 1#body_extension]]
3677 
+                    ;; MUST NOT be returned on non-extensible
3678 
+                    ;; "BODY" fetch
3679 
+
3680 
+body_fields     ::= body_fld_param SPACE body_fld_id SPACE
3681 
+                    body_fld_desc SPACE body_fld_enc SPACE
3682 
+                    body_fld_octets
3683 
+
3684 
+body_fld_desc   ::= nstring
3685 
+
3686 
+body_fld_dsp    ::= "(" string SPACE body_fld_param ")" / nil
3687 
+
3688 
+body_fld_enc    ::= (<"> ("7BIT" / "8BIT" / "BINARY" / "BASE64"/
3689 
+                    "QUOTED-PRINTABLE") <">) / string
3690 
+
3691 
+body_fld_id     ::= nstring
3692 
+
3693 
+body_fld_lang   ::= nstring / "(" 1#string ")"
3694 
+
3695 
+
3696 
+
3697 
+
3698 
+Crispin                     Standards Track                    [Page 66]
3699 
+
3700 
+RFC 2060                       IMAP4rev1                   December 1996
3701 
+
3702 
+
3703 
+body_fld_lines  ::= number
3704 
+
3705 
+body_fld_md5    ::= nstring
3706 
+
3707 
+body_fld_octets ::= number
3708 
+
3709 
+body_fld_param  ::= "(" 1#(string SPACE string) ")" / nil
3710 
+
3711 
+body_type_1part ::= (body_type_basic / body_type_msg / body_type_text)
3712 
+                    [SPACE body_ext_1part]
3713 
+
3714 
+body_type_basic ::= media_basic SPACE body_fields
3715 
+                    ;; MESSAGE subtype MUST NOT be "RFC822"
3716 
+
3717 
+body_type_mpart ::= 1*body SPACE media_subtype
3718 
+                    [SPACE body_ext_mpart]
3719 
+
3720 
+body_type_msg   ::= media_message SPACE body_fields SPACE envelope
3721 
+                    SPACE body SPACE body_fld_lines
3722 
+
3723 
+body_type_text  ::= media_text SPACE body_fields SPACE body_fld_lines
3724 
+
3725 
+capability      ::= "AUTH=" auth_type / atom
3726 
+                    ;; New capabilities MUST begin with "X" or be
3727 
+                    ;; registered with IANA as standard or
3728 
+                    ;; standards-track
3729 
+
3730 
+capability_data ::= "CAPABILITY" SPACE [1#capability SPACE] "IMAP4rev1"
3731 
+                    [SPACE 1#capability]
3732 
+                    ;; IMAP4rev1 servers which offer RFC 1730
3733 
+                    ;; compatibility MUST list "IMAP4" as the first
3734 
+                    ;; capability.
3735 
+
3736 
+CHAR            ::= <any 7-bit US-ASCII character except NUL,
3737 
+                     0x01 - 0x7f>
3738 
+
3739 
+CHAR8           ::= <any 8-bit octet except NUL, 0x01 - 0xff>
3740 
+
3741 
+command         ::= tag SPACE (command_any / command_auth /
3742 
+                    command_nonauth / command_select) CRLF
3743 
+                    ;; Modal based on state
3744 
+
3745 
+command_any     ::= "CAPABILITY" / "LOGOUT" / "NOOP" / x_command
3746 
+                    ;; Valid in all states
3747 
+
3748 
+command_auth    ::= append / create / delete / examine / list / lsub /
3749 
+                    rename / select / status / subscribe / unsubscribe
3750 
+                    ;; Valid only in Authenticated or Selected state
3751 
+
3752 
+
3753 
+
3754 
+Crispin                     Standards Track                    [Page 67]
3755 
+
3756 
+RFC 2060                       IMAP4rev1                   December 1996
3757 
+
3758 
+
3759 
+command_nonauth ::= login / authenticate
3760 
+                    ;; Valid only when in Non-Authenticated state
3761 
+
3762 
+command_select  ::= "CHECK" / "CLOSE" / "EXPUNGE" /
3763 
+                     copy / fetch / store / uid / search
3764 
+                    ;; Valid only when in Selected state
3765 
+
3766 
+continue_req    ::= "+" SPACE (resp_text / base64)
3767 
+
3768 
+copy            ::= "COPY" SPACE set SPACE mailbox
3769 
+
3770 
+CR              ::= <ASCII CR, carriage return, 0x0D>
3771 
+
3772 
+create          ::= "CREATE" SPACE mailbox
3773 
+                    ;; Use of INBOX gives a NO error
3774 
+
3775 
+CRLF            ::= CR LF
3776 
+
3777 
+CTL             ::= <any ASCII control character and DEL,
3778 
+                        0x00 - 0x1f, 0x7f>
3779 
+
3780 
+date            ::= date_text / <"> date_text <">
3781 
+
3782 
+date_day        ::= 1*2digit
3783 
+                    ;; Day of month
3784 
+
3785 
+date_day_fixed  ::= (SPACE digit) / 2digit
3786 
+                    ;; Fixed-format version of date_day
3787 
+
3788 
+date_month      ::= "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
3789 
+                    "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
3790 
+
3791 
+date_text       ::= date_day "-" date_month "-" date_year
3792 
+
3793 
+date_year       ::= 4digit
3794 
+
3795 
+date_time       ::= <"> date_day_fixed "-" date_month "-" date_year
3796 
+                    SPACE time SPACE zone <">
3797 
+
3798 
+delete          ::= "DELETE" SPACE mailbox
3799 
+                    ;; Use of INBOX gives a NO error
3800 
+
3801 
+digit           ::= "0" / digit_nz
3802 
+
3803 
+digit_nz        ::= "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" /
3804 
+                    "9"
3805 
+
3806 
+
3807 
+
3808 
+
3809 
+
3810 
+Crispin                     Standards Track                    [Page 68]
3811 
+
3812 
+RFC 2060                       IMAP4rev1                   December 1996
3813 
+
3814 
+
3815 
+envelope        ::= "(" env_date SPACE env_subject SPACE env_from
3816 
+                    SPACE env_sender SPACE env_reply_to SPACE env_to
3817 
+                    SPACE env_cc SPACE env_bcc SPACE env_in_reply_to
3818 
+                    SPACE env_message_id ")"
3819 
+
3820 
+env_bcc         ::= "(" 1*address ")" / nil
3821 
+
3822 
+env_cc          ::= "(" 1*address ")" / nil
3823 
+
3824 
+env_date        ::= nstring
3825 
+
3826 
+env_from        ::= "(" 1*address ")" / nil
3827 
+
3828 
+env_in_reply_to ::= nstring
3829 
+
3830 
+env_message_id  ::= nstring
3831 
+
3832 
+env_reply_to    ::= "(" 1*address ")" / nil
3833 
+
3834 
+env_sender      ::= "(" 1*address ")" / nil
3835 
+
3836 
+env_subject     ::= nstring
3837 
+
3838 
+env_to          ::= "(" 1*address ")" / nil
3839 
+
3840 
+examine         ::= "EXAMINE" SPACE mailbox
3841 
+
3842 
+fetch           ::= "FETCH" SPACE set SPACE ("ALL" / "FULL" /
3843 
+                    "FAST" / fetch_att / "(" 1#fetch_att ")")
3844 
+
3845 
+fetch_att       ::= "ENVELOPE" / "FLAGS" / "INTERNALDATE" /
3846 
+                    "RFC822" [".HEADER" / ".SIZE" / ".TEXT"] /
3847 
+                    "BODY" ["STRUCTURE"] / "UID" /
3848 
+                    "BODY" [".PEEK"] section
3849 
+                    ["<" number "." nz_number ">"]
3850 
+
3851 
+flag            ::= "\Answered" / "\Flagged" / "\Deleted" /
3852 
+                    "\Seen" / "\Draft" / flag_keyword / flag_extension
3853 
+
3854 
+flag_extension  ::= "\" atom
3855 
+                    ;; Future expansion.  Client implementations
3856 
+                    ;; MUST accept flag_extension flags.  Server
3857 
+                    ;; implementations MUST NOT generate
3858 
+                    ;; flag_extension flags except as defined by
3859 
+                    ;; future standard or standards-track
3860 
+                    ;; revisions of this specification.
3861 
+
3862 
+flag_keyword    ::= atom
3863 
+
3864 
+
3865 
+
3866 
+Crispin                     Standards Track                    [Page 69]
3867 
+
3868 
+RFC 2060                       IMAP4rev1                   December 1996
3869 
+
3870 
+
3871 
+flag_list       ::= "(" #flag ")"
3872 
+
3873 
+greeting        ::= "*" SPACE (resp_cond_auth / resp_cond_bye) CRLF
3874 
+
3875 
+header_fld_name ::= astring
3876 
+
3877 
+header_list     ::= "(" 1#header_fld_name ")"
3878 
+
3879 
+LF              ::= <ASCII LF, line feed, 0x0A>
3880 
+
3881 
+list            ::= "LIST" SPACE mailbox SPACE list_mailbox
3882 
+
3883 
+list_mailbox    ::= 1*(ATOM_CHAR / list_wildcards) / string
3884 
+
3885 
+list_wildcards  ::= "%" / "*"
3886 
+
3887 
+literal         ::= "{" number "}" CRLF *CHAR8
3888 
+                    ;; Number represents the number of CHAR8 octets
3889 
+
3890 
+login           ::= "LOGIN" SPACE userid SPACE password
3891 
+
3892 
+lsub            ::= "LSUB" SPACE mailbox SPACE list_mailbox
3893 
+
3894 
+mailbox         ::= "INBOX" / astring
3895 
+                    ;; INBOX is case-insensitive.  All case variants of
3896 
+                    ;; INBOX (e.g. "iNbOx") MUST be interpreted as INBOX
3897 
+                    ;; not as an astring.  Refer to section 5.1 for
3898 
+                    ;; further semantic details of mailbox names.
3899 
+
3900 
+mailbox_data    ::=  "FLAGS" SPACE flag_list /
3901 
+                     "LIST" SPACE mailbox_list /
3902 
+                     "LSUB" SPACE mailbox_list /
3903 
+                     "MAILBOX" SPACE text /
3904 
+                     "SEARCH" [SPACE 1#nz_number] /
3905 
+                     "STATUS" SPACE mailbox SPACE
3906 
+                     "(" #<status_att number ")" /
3907 
+                     number SPACE "EXISTS" / number SPACE "RECENT"
3908 
+
3909 
+mailbox_list    ::= "(" #("\Marked" / "\Noinferiors" /
3910 
+                    "\Noselect" / "\Unmarked" / flag_extension) ")"
3911 
+                    SPACE (<"> QUOTED_CHAR <"> / nil) SPACE mailbox
3912 
+
3913 
+media_basic     ::= (<"> ("APPLICATION" / "AUDIO" / "IMAGE" /
3914 
+                    "MESSAGE" / "VIDEO") <">) / string)
3915 
+                    SPACE media_subtype
3916 
+                    ;; Defined in [MIME-IMT]
3917 
+
3918 
+media_message   ::= <"> "MESSAGE" <"> SPACE <"> "RFC822" <">
3919 
+
3920 
+
3921 
+
3922 
+Crispin                     Standards Track                    [Page 70]
3923 
+
3924 
+RFC 2060                       IMAP4rev1                   December 1996
3925 
+
3926 
+
3927 
+                    ;; Defined in [MIME-IMT]
3928 
+
3929 
+media_subtype   ::= string
3930 
+                    ;; Defined in [MIME-IMT]
3931 
+
3932 
+media_text      ::= <"> "TEXT" <"> SPACE media_subtype
3933 
+                    ;; Defined in [MIME-IMT]
3934 
+
3935 
+message_data    ::= nz_number SPACE ("EXPUNGE" /
3936 
+                                    ("FETCH" SPACE msg_att))
3937 
+
3938 
+msg_att         ::= "(" 1#("ENVELOPE" SPACE envelope /
3939 
+                    "FLAGS" SPACE "(" #(flag / "\Recent") ")" /
3940 
+                    "INTERNALDATE" SPACE date_time /
3941 
+                    "RFC822" [".HEADER" / ".TEXT"] SPACE nstring /
3942 
+                    "RFC822.SIZE" SPACE number /
3943 
+                    "BODY" ["STRUCTURE"] SPACE body /
3944 
+                    "BODY" section ["<" number ">"] SPACE nstring /
3945 
+                    "UID" SPACE uniqueid) ")"
3946 
+
3947 
+nil             ::= "NIL"
3948 
+
3949 
+nstring         ::= string / nil
3950 
+
3951 
+number          ::= 1*digit
3952 
+                    ;; Unsigned 32-bit integer
3953 
+                    ;; (0 <= n < 4,294,967,296)
3954 
+
3955 
+nz_number       ::= digit_nz *digit
3956 
+                    ;; Non-zero unsigned 32-bit integer
3957 
+                    ;; (0 < n < 4,294,967,296)
3958 
+
3959 
+password        ::= astring
3960 
+
3961 
+quoted          ::= <"> *QUOTED_CHAR <">
3962 
+
3963 
+QUOTED_CHAR     ::= <any TEXT_CHAR except quoted_specials> /
3964 
+                    "\" quoted_specials
3965 
+
3966 
+quoted_specials ::= <"> / "\"
3967 
+
3968 
+rename          ::= "RENAME" SPACE mailbox SPACE mailbox
3969 
+                    ;; Use of INBOX as a destination gives a NO error
3970 
+
3971 
+response        ::= *(continue_req / response_data) response_done
3972 
+
3973 
+response_data   ::= "*" SPACE (resp_cond_state / resp_cond_bye /
3974 
+                    mailbox_data / message_data / capability_data)
3975 
+
3976 
+
3977 
+
3978 
+Crispin                     Standards Track                    [Page 71]
3979 
+
3980 
+RFC 2060                       IMAP4rev1                   December 1996
3981 
+
3982 
+
3983 
+                    CRLF
3984 
+
3985 
+response_done   ::= response_tagged / response_fatal
3986 
+
3987 
+response_fatal  ::= "*" SPACE resp_cond_bye CRLF
3988 
+                    ;; Server closes connection immediately
3989 
+
3990 
+response_tagged ::= tag SPACE resp_cond_state CRLF
3991 
+
3992 
+resp_cond_auth  ::= ("OK" / "PREAUTH") SPACE resp_text
3993 
+                    ;; Authentication condition
3994 
+
3995 
+resp_cond_bye   ::= "BYE" SPACE resp_text
3996 
+
3997 
+resp_cond_state ::= ("OK" / "NO" / "BAD") SPACE resp_text
3998 
+                    ;; Status condition
3999 
+
4000 
+resp_text       ::= ["[" resp_text_code "]" SPACE] (text_mime2 / text)
4001 
+                    ;; text SHOULD NOT begin with "[" or "="
4002 
+
4003 
+resp_text_code  ::= "ALERT" / "PARSE" /
4004 
+                    "PERMANENTFLAGS" SPACE "(" #(flag / "\*") ")" /
4005 
+                    "READ-ONLY" / "READ-WRITE" / "TRYCREATE" /
4006 
+                    "UIDVALIDITY" SPACE nz_number /
4007 
+                    "UNSEEN" SPACE nz_number /
4008 
+                    atom [SPACE 1*<any TEXT_CHAR except "]">]
4009 
+
4010 
+search          ::= "SEARCH" SPACE ["CHARSET" SPACE astring SPACE]
4011 
+                    1#search_key
4012 
+                    ;; [CHARSET] MUST be registered with IANA
4013 
+
4014 
+search_key      ::= "ALL" / "ANSWERED" / "BCC" SPACE astring /
4015 
+                    "BEFORE" SPACE date / "BODY" SPACE astring /
4016 
+                    "CC" SPACE astring / "DELETED" / "FLAGGED" /
4017 
+                    "FROM" SPACE astring /
4018 
+                    "KEYWORD" SPACE flag_keyword / "NEW" / "OLD" /
4019 
+                    "ON" SPACE date / "RECENT" / "SEEN" /
4020 
+                    "SINCE" SPACE date / "SUBJECT" SPACE astring /
4021 
+                    "TEXT" SPACE astring / "TO" SPACE astring /
4022 
+                    "UNANSWERED" / "UNDELETED" / "UNFLAGGED" /
4023 
+                    "UNKEYWORD" SPACE flag_keyword / "UNSEEN" /
4024 
+                    ;; Above this line were in [IMAP2]
4025 
+                    "DRAFT" /
4026 
+                    "HEADER" SPACE header_fld_name SPACE astring /
4027 
+                    "LARGER" SPACE number / "NOT" SPACE search_key /
4028 
+                    "OR" SPACE search_key SPACE search_key /
4029 
+                    "SENTBEFORE" SPACE date / "SENTON" SPACE date /
4030 
+                    "SENTSINCE" SPACE date / "SMALLER" SPACE number /
4031 
+
4032 
+
4033 
+
4034 
+Crispin                     Standards Track                    [Page 72]
4035 
+
4036 
+RFC 2060                       IMAP4rev1                   December 1996
4037 
+
4038 
+
4039 
+                    "UID" SPACE set / "UNDRAFT" / set /
4040 
+                    "(" 1#search_key ")"
4041 
+
4042 
+section         ::= "[" [section_text / (nz_number *["." nz_number]
4043 
+                    ["." (section_text / "MIME")])] "]"
4044 
+
4045 
+section_text    ::= "HEADER" / "HEADER.FIELDS" [".NOT"]
4046 
+                    SPACE header_list / "TEXT"
4047 
+
4048 
+select          ::= "SELECT" SPACE mailbox
4049 
+
4050 
+sequence_num    ::= nz_number / "*"
4051 
+                    ;; * is the largest number in use.  For message
4052 
+                    ;; sequence numbers, it is the number of messages
4053 
+                    ;; in the mailbox.  For unique identifiers, it is
4054 
+                    ;; the unique identifier of the last message in
4055 
+                    ;; the mailbox.
4056 
+
4057 
+set             ::= sequence_num / (sequence_num ":" sequence_num) /
4058 
+                    (set "," set)
4059 
+                    ;; Identifies a set of messages.  For message
4060 
+                    ;; sequence numbers, these are consecutive
4061 
+                    ;; numbers from 1 to the number of messages in
4062 
+                    ;; the mailbox
4063 
+                    ;; Comma delimits individual numbers, colon
4064 
+                    ;; delimits between two numbers inclusive.
4065 
+                    ;; Example: 2,4:7,9,12:* is 2,4,5,6,7,9,12,13,
4066 
+                    ;; 14,15 for a mailbox with 15 messages.
4067 
+
4068 
+SPACE           ::= <ASCII SP, space, 0x20>
4069 
+
4070 
+status          ::= "STATUS" SPACE mailbox SPACE "(" 1#status_att ")"
4071 
+
4072 
+status_att      ::= "MESSAGES" / "RECENT" / "UIDNEXT" / "UIDVALIDITY" /
4073 
+                    "UNSEEN"
4074 
+
4075 
+store           ::= "STORE" SPACE set SPACE store_att_flags
4076 
+
4077 
+store_att_flags ::= (["+" / "-"] "FLAGS" [".SILENT"]) SPACE
4078 
+                    (flag_list / #flag)
4079 
+
4080 
+string          ::= quoted / literal
4081 
+
4082 
+subscribe       ::= "SUBSCRIBE" SPACE mailbox
4083 
+
4084 
+tag             ::= 1*<any ATOM_CHAR except "+">
4085 
+
4086 
+text            ::= 1*TEXT_CHAR
4087 
+
4088 
+
4089 
+
4090 
+Crispin                     Standards Track                    [Page 73]
4091 
+
4092 
+RFC 2060                       IMAP4rev1                   December 1996
4093 
+
4094 
+
4095 
+text_mime2       ::= "=?" <charset> "?" <encoding> "?"
4096 
+                     <encoded-text> "?="
4097 
+                     ;; Syntax defined in [MIME-HDRS]
4098 
+
4099 
+TEXT_CHAR       ::= <any CHAR except CR and LF>
4100 
+
4101 
+time            ::= 2digit ":" 2digit ":" 2digit
4102 
+                    ;; Hours minutes seconds
4103 
+
4104 
+uid             ::= "UID" SPACE (copy / fetch / search / store)
4105 
+                    ;; Unique identifiers used instead of message
4106 
+                    ;; sequence numbers
4107 
+
4108 
+uniqueid        ::= nz_number
4109 
+                    ;; Strictly ascending
4110 
+
4111 
+unsubscribe     ::= "UNSUBSCRIBE" SPACE mailbox
4112 
+
4113 
+userid          ::= astring
4114 
+
4115 
+x_command       ::= "X" atom <experimental command arguments>
4116 
+
4117 
+zone            ::= ("+" / "-") 4digit
4118 
+                    ;; Signed four-digit value of hhmm representing
4119 
+                    ;; hours and minutes west of Greenwich (that is,
4120 
+                    ;; (the amount that the given time differs from
4121 
+                    ;; Universal Time).  Subtracting the timezone
4122 
+                    ;; from the given time will give the UT form.
4123 
+                    ;; The Universal Time zone is "+0000".
4124 
+
4125 
+10.     Author's Note
4126 
+
4127 
+   This document is a revision or rewrite of earlier documents, and
4128 
+   supercedes the protocol specification in those documents: RFC 1730,
4129 
+   unpublished IMAP2bis.TXT document, RFC 1176, and RFC 1064.
4130 
+
4131 
+11.     Security Considerations
4132 
+
4133 
+   IMAP4rev1 protocol transactions, including electronic mail data, are
4134 
+   sent in the clear over the network unless privacy protection is
4135 
+   negotiated in the AUTHENTICATE command.
4136 
+
4137 
+   A server error message for an AUTHENTICATE command which fails due to
4138 
+   invalid credentials SHOULD NOT detail why the credentials are
4139 
+   invalid.
4140 
+
4141 
+   Use of the LOGIN command sends passwords in the clear.  This can be
4142 
+   avoided by using the AUTHENTICATE command instead.
4143 
+
4144 
+
4145 
+
4146 
+Crispin                     Standards Track                    [Page 74]
4147 
+
4148 
+RFC 2060                       IMAP4rev1                   December 1996
4149 
+
4150 
+
4151 
+   A server error message for a failing LOGIN command SHOULD NOT specify
4152 
+   that the user name, as opposed to the password, is invalid.
4153 
+
4154 
+   Additional security considerations are discussed in the section
4155 
+   discussing the AUTHENTICATE and LOGIN commands.
4156 
+
4157 
+12.     Author's Address
4158 
+
4159 
+   Mark R. Crispin
4160 
+   Networks and Distributed Computing
4161 
+   University of Washington
4162 
+   4545 15th Aveneue NE
4163 
+   Seattle, WA  98105-4527
4164 
+
4165 
+   Phone: (206) 543-5762
4166 
+
4167 
+   EMail: MRC@CAC.Washington.EDU
4168 
+
4169 
+
4170 
+
4171 
+
4172 
+
4173 
+
4174 
+
4175 
+
4176 
+
4177 
+
4178 
+
4179 
+
4180 
+
4181 
+
4182 
+
4183 
+
4184 
+
4185 
+
4186 
+
4187 
+
4188 
+
4189 
+
4190 
+
4191 
+
4192 
+
4193 
+
4194 
+
4195 
+
4196 
+
4197 
+
4198 
+
4199 
+
4200 
+
4201 
+
4202 
+Crispin                     Standards Track                    [Page 75]
4203 
+
4204 
+RFC 2060                       IMAP4rev1                   December 1996
4205 
+
4206 
+
4207 
+Appendices
4208 
+
4209 
+A.      References
4210 
+
4211 
+[ACAP] Myers, J. "ACAP -- Application Configuration Access Protocol",
4212 
+Work in Progress.
4213 
+
4214 
+[CHARSET] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2,
4215 
+RFC 1700, USC/Information Sciences Institute, October 1994.
4216 
+
4217 
+[DISPOSITION] Troost, R., and Dorner, S., "Communicating Presentation
4218 
+Information in Internet Messages: The Content-Disposition Header",
4219 
+RFC 1806, June 1995.
4220 
+
4221 
+[IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanism", RFC 1731.
4222 
+Carnegie-Mellon University, December 1994.
4223 
+
4224 
+[IMAP-COMPAT] Crispin, M., "IMAP4 Compatibility with IMAP2bis", RFC
4225 
+2061, University of Washington, November 1996.
4226 
+
4227 
+[IMAP-DISC] Austein, R., "Synchronization Operations for Disconnected
4228 
+IMAP4 Clients", Work in Progress.
4229 
+
4230 
+[IMAP-HISTORICAL] Crispin, M. "IMAP4 Compatibility with IMAP2 and
4231 
+IMAP2bis", RFC 1732, University of Washington, December 1994.
4232 
+
4233 
+[IMAP-MODEL] Crispin, M., "Distributed Electronic Mail Models in
4234 
+IMAP4", RFC 1733, University of Washington, December 1994.
4235 
+
4236 
+[IMAP-OBSOLETE] Crispin, M., "Internet Message Access Protocol -
4237 
+Obsolete Syntax", RFC 2062, University of Washington, November 1996.
4238 
+
4239 
+[IMAP2] Crispin, M., "Interactive Mail Access Protocol - Version 2",
4240 
+RFC 1176, University of Washington, August 1990.
4241 
+
4242 
+[LANGUAGE-TAGS] Alvestrand, H., "Tags for the Identification of
4243 
+Languages", RFC 1766, March 1995.
4244 
+
4245 
+[MD5] Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
4246 
+1864, October 1995.
4247 
+
4248 
+[MIME-IMB] Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
4249 
+Mail Extensions) Part One: Format of Internet Message Bodies", RFC
4250 
+2045, November 1996.
4251 
+
4252 
+[MIME-IMT] Freed, N., and N. Borenstein, "MIME (Multipurpose
4253 
+Internet Mail Extensions) Part Two: Media Types", RFC 2046,
4254 
+November 1996.
4255 
+
4256 
+
4257 
+
4258 
+Crispin                     Standards Track                    [Page 76]
4259 
+
4260 
+RFC 2060                       IMAP4rev1                   December 1996
4261 
+
4262 
+
4263 
+[MIME-HDRS] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
4264 
+Part Three: Message Header Extensions for Non-ASCII Text", RFC
4265 
+2047, November 1996.
4266 
+
4267 
+[RFC-822] Crocker, D., "Standard for the Format of ARPA Internet Text
4268 
+Messages", STD 11, RFC 822, University of Delaware, August 1982.
4269 
+
4270 
+[SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10,
4271 
+RFC 821, USC/Information Sciences Institute, August 1982.
4272 
+
4273 
+[UTF-7] Goldsmith, D., and Davis, M., "UTF-7: A Mail-Safe
4274 
+Transformation Format of Unicode", RFC 1642, July 1994.
4275 
+
4276 
+B.      Changes from RFC 1730
4277 
+
4278 
+1) The STATUS command has been added.
4279 
+
4280 
+2) Clarify in the formal syntax that the "#" construct can never
4281 
+refer to multiple spaces.
4282 
+
4283 
+3) Obsolete syntax has been moved to a separate document.
4284 
+
4285 
+4) The PARTIAL command has been obsoleted.
4286 
+
4287 
+5) The RFC822.HEADER.LINES, RFC822.HEADER.LINES.NOT, RFC822.PEEK, and
4288 
+RFC822.TEXT.PEEK fetch attributes have been obsoleted.
4289 
+
4290 
+6) The "<" origin "." size ">" suffix for BODY text attributes has
4291 
+been added.
4292 
+
4293 
+7) The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, MIME, and TEXT part
4294 
+specifiers have been added.
4295 
+
4296 
+8) Support for Content-Disposition and Content-Language has been
4297 
+added.
4298 
+
4299 
+9) The restriction on fetching nested MULTIPART parts has been
4300 
+removed.
4301 
+
4302 
+10) Body part number 0 has been obsoleted.
4303 
+
4304 
+11) Server-supported authenticators are now identified by
4305 
+capabilities.
4306 
+
4307 
+
4308 
+
4309 
+
4310 
+
4311 
+
4312 
+
4313 
+
4314 
+Crispin                     Standards Track                    [Page 77]
4315 
+
4316 
+RFC 2060                       IMAP4rev1                   December 1996
4317 
+
4318 
+
4319 
+12) The capability that identifies this protocol is now called
4320 
+"IMAP4rev1".  A server that provides backwards support for RFC 1730
4321 
+SHOULD emit the "IMAP4" capability in addition to "IMAP4rev1" in its
4322 
+CAPABILITY response.  Because RFC-1730 required "IMAP4" to appear as
4323 
+the first capability, it MUST listed first in the response.
4324 
+
4325 
+13) A description of the mailbox name namespace convention has been
4326 
+added.
4327 
+
4328 
+14) A description of the international mailbox name convention has
4329 
+been added.
4330 
+
4331 
+15) The UID-NEXT and UID-VALIDITY status items are now called UIDNEXT
4332 
+and UIDVALIDITY.  This is a change from the IMAP STATUS
4333 
+Work in Progress and not from RFC-1730
4334 
+
4335 
+16) Add a clarification that a null mailbox name argument to the LIST
4336 
+command returns an untagged LIST response with the hierarchy
4337 
+delimiter and root of the reference argument.
4338 
+
4339 
+17) Define terms such as "MUST", "SHOULD", and "MUST NOT".
4340 
+
4341 
+18) Add a section which defines message attributes and more
4342 
+thoroughly details the semantics of message sequence numbers, UIDs,
4343 
+and flags.
4344 
+
4345 
+19) Add a clarification detailing the circumstances when a client may
4346 
+send multiple commands without waiting for a response, and the
4347 
+circumstances in which ambiguities may result.
4348 
+
4349 
+20) Add a recommendation on server behavior for DELETE and RENAME
4350 
+when inferior hierarchical names of the given name exist.
4351 
+
4352 
+21) Add a clarification that a mailbox name may not be unilaterally
4353 
+unsubscribed by the server, even if that mailbox name no longer
4354 
+exists.
4355 
+
4356 
+22) Add a clarification that LIST should return its results quickly
4357 
+without undue delay.
4358 
+
4359 
+23) Add a clarification that the date_time argument to APPEND sets
4360 
+the internal date of the message.
4361 
+
4362 
+24) Add a clarification on APPEND behavior when the target mailbox is
4363 
+the currently selected mailbox.
4364 
+
4365 
+
4366 
+
4367 
+
4368 
+
4369 
+
4370 
+Crispin                     Standards Track                    [Page 78]
4371 
+
4372 
+RFC 2060                       IMAP4rev1                   December 1996
4373 
+
4374 
+
4375 
+25) Add a clarification that external changes to flags should be
4376 
+always announced via an untagged FETCH even if the current command is
4377 
+a STORE with the ".SILENT" suffix.
4378 
+
4379 
+26) Add a clarification that COPY appends to the target mailbox.
4380 
+
4381 
+27) Add the NEWNAME response code.
4382 
+
4383 
+28) Rewrite the description of the untagged BYE response to clarify
4384 
+its semantics.
4385 
+
4386 
+29) Change the reference for the body MD5 to refer to the proper RFC.
4387 
+
4388 
+30) Clarify that the formal syntax contains rules which may overlap,
4389 
+and that in the event of such an overlap the rule which occurs first
4390 
+takes precedence.
4391 
+
4392 
+31) Correct the definition of body_fld_param.
4393 
+
4394 
+32) More formal syntax for capability_data.
4395 
+
4396 
+33) Clarify that any case variant of "INBOX" must be interpreted as
4397 
+INBOX.
4398 
+
4399 
+34) Clarify that the human-readable text in resp_text should not
4400 
+begin with "[" or "=".
4401 
+
4402 
+35) Change MIME references to Draft Standard documents.
4403 
+
4404 
+36) Clarify \Recent semantics.
4405 
+
4406 
+37) Additional examples.
4407 
+
4408 
+C.      Key Word Index
4409 
+
4410 
+       +FLAGS <flag list> (store command data item) ...............   45
4411 
+       +FLAGS.SILENT <flag list> (store command data item) ........   46
4412 
+       -FLAGS <flag list> (store command data item) ...............   46
4413 
+       -FLAGS.SILENT <flag list> (store command data item) ........   46
4414 
+       ALERT (response code) ......................................   50
4415 
+       ALL (fetch item) ...........................................   41
4416 
+       ALL (search key) ...........................................   38
4417 
+       ANSWERED (search key) ......................................   38
4418 
+       APPEND (command) ...........................................   34
4419 
+       AUTHENTICATE (command) .....................................   20
4420 
+       BAD (response) .............................................   52
4421 
+       BCC <string> (search key) ..................................   38
4422 
+       BEFORE <date> (search key) .................................   39
4423 
+
4424 
+
4425 
+
4426 
+Crispin                     Standards Track                    [Page 79]
4427 
+
4428 
+RFC 2060                       IMAP4rev1                   December 1996
4429 
+
4430 
+
4431 
+       BODY (fetch item) ..........................................   41
4432 
+       BODY (fetch result) ........................................   58
4433 
+       BODY <string> (search key) .................................   39
4434 
+       BODY.PEEK[<section>]<<partial>> (fetch item) ...............   44
4435 
+       BODYSTRUCTURE (fetch item) .................................   44
4436 
+       BODYSTRUCTURE (fetch result) ...............................   59
4437 
+       BODY[<section>]<<origin_octet>> (fetch result) .............   58
4438 
+       BODY[<section>]<<partial>> (fetch item) ....................   41
4439 
+       BYE (response) .............................................   52
4440 
+       Body Structure (message attribute) .........................   11
4441 
+       CAPABILITY (command) .......................................   18
4442 
+       CAPABILITY (response) ......................................   53
4443 
+       CC <string> (search key) ...................................   39
4444 
+       CHECK (command) ............................................   36
4445 
+       CLOSE (command) ............................................   36
4446 
+       COPY (command) .............................................   46
4447 
+       CREATE (command) ...........................................   25
4448 
+       DELETE (command) ...........................................   26
4449 
+       DELETED (search key) .......................................   39
4450 
+       DRAFT (search key) .........................................   39
4451 
+       ENVELOPE (fetch item) ......................................   44
4452 
+       ENVELOPE (fetch result) ....................................   62
4453 
+       EXAMINE (command) ..........................................   24
4454 
+       EXISTS (response) ..........................................   56
4455 
+       EXPUNGE (command) ..........................................   37
4456 
+       EXPUNGE (response) .........................................   57
4457 
+       Envelope Structure (message attribute) .....................   11
4458 
+       FAST (fetch item) ..........................................   44
4459 
+       FETCH (command) ............................................   41
4460 
+       FETCH (response) ...........................................   58
4461 
+       FLAGGED (search key) .......................................   39
4462 
+       FLAGS (fetch item) .........................................   44
4463 
+       FLAGS (fetch result) .......................................   62
4464 
+       FLAGS (response) ...........................................   56
4465 
+       FLAGS <flag list> (store command data item) ................   45
4466 
+       FLAGS.SILENT <flag list> (store command data item) .........   45
4467 
+       FROM <string> (search key) .................................   39
4468 
+       FULL (fetch item) ..........................................   44
4469 
+       Flags (message attribute) ..................................    9
4470 
+       HEADER (part specifier) ....................................   41
4471 
+       HEADER <field-name> <string> (search key) ..................   39
4472 
+       HEADER.FIELDS <header_list> (part specifier) ...............   41
4473 
+       HEADER.FIELDS.NOT <header_list> (part specifier) ...........   41
4474 
+       INTERNALDATE (fetch item) ..................................   44
4475 
+       INTERNALDATE (fetch result) ................................   62
4476 
+       Internal Date (message attribute) ..........................   10
4477 
+       KEYWORD <flag> (search key) ................................   39
4478 
+       Keyword (type of flag) .....................................   10
4479 
+
4480 
+
4481 
+
4482 
+Crispin                     Standards Track                    [Page 80]
4483 
+
4484 
+RFC 2060                       IMAP4rev1                   December 1996
4485 
+
4486 
+
4487 
+       LARGER <n> (search key) ....................................   39
4488 
+       LIST (command) .............................................   30
4489 
+       LIST (response) ............................................   54
4490 
+       LOGIN (command) ............................................   22
4491 
+       LOGOUT (command) ...........................................   20
4492 
+       LSUB (command) .............................................   32
4493 
+       LSUB (response) ............................................   55
4494 
+       MAY (specification requirement term) .......................    5
4495 
+       MESSAGES (status item) .....................................   33
4496 
+       MIME (part specifier) ......................................   42
4497 
+       MUST (specification requirement term) ......................    4
4498 
+       MUST NOT (specification requirement term) ..................    4
4499 
+       Message Sequence Number (message attribute) ................    9
4500 
+       NEW (search key) ...........................................   39
4501 
+       NEWNAME (response code) ....................................   50
4502 
+       NO (response) ..............................................   51
4503 
+       NOOP (command) .............................................   19
4504 
+       NOT <search-key> (search key) ..............................   39
4505 
+       OK (response) ..............................................   51
4506 
+       OLD (search key) ...........................................   39
4507 
+       ON <date> (search key) .....................................   39
4508 
+       OPTIONAL (specification requirement term) ..................    5
4509 
+       OR <search-key1> <search-key2> (search key) ................   39
4510 
+       PARSE (response code) ......................................   50
4511 
+       PERMANENTFLAGS (response code) .............................   50
4512 
+       PREAUTH (response) .........................................   52
4513 
+       Permanent Flag (class of flag) .............................   10
4514 
+       READ-ONLY (response code) ..................................   50
4515 
+       READ-WRITE (response code) .................................   50
4516 
+       RECENT (response) ..........................................   57
4517 
+       RECENT (search key) ........................................   39
4518 
+       RECENT (status item) .......................................   33
4519 
+       RENAME (command) ...........................................   27
4520 
+       REQUIRED (specification requirement term) ..................    4
4521 
+       RFC822 (fetch item) ........................................   44
4522 
+       RFC822 (fetch result) ......................................   63
4523 
+       RFC822.HEADER (fetch item) .................................   44
4524 
+       RFC822.HEADER (fetch result) ...............................   62
4525 
+       RFC822.SIZE (fetch item) ...................................   44
4526 
+       RFC822.SIZE (fetch result) .................................   62
4527 
+       RFC822.TEXT (fetch item) ...................................   44
4528 
+       RFC822.TEXT (fetch result) .................................   62
4529 
+       SEARCH (command) ...........................................   37
4530 
+       SEARCH (response) ..........................................   55
4531 
+       SEEN (search key) ..........................................   40
4532 
+       SELECT (command) ...........................................   23
4533 
+       SENTBEFORE <date> (search key) .............................   40
4534 
+       SENTON <date> (search key) .................................   40
4535 
+
4536 
+
4537 
+
4538 
+Crispin                     Standards Track                    [Page 81]
4539 
+
4540 
+RFC 2060                       IMAP4rev1                   December 1996
4541 
+
4542 
+
4543 
+       SENTSINCE <date> (search key) ..............................   40
4544 
+       SHOULD (specification requirement term) ....................    5
4545 
+       SHOULD NOT (specification requirement term) ................    5
4546 
+       SINCE <date> (search key) ..................................   40
4547 
+       SMALLER <n> (search key) ...................................   40
4548 
+       STATUS (command) ...........................................   33
4549 
+       STATUS (response) ..........................................   55
4550 
+       STORE (command) ............................................   45
4551 
+       SUBJECT <string> (search key) ..............................   40
4552 
+       SUBSCRIBE (command) ........................................   29
4553 
+       Session Flag (class of flag) ...............................   10
4554 
+       System Flag (type of flag) .................................    9
4555 
+       TEXT (part specifier) ......................................   42
4556 
+       TEXT <string> (search key) .................................   40
4557 
+       TO <string> (search key) ...................................   40
4558 
+       TRYCREATE (response code) ..................................   51
4559 
+       UID (command) ..............................................   47
4560 
+       UID (fetch item) ...........................................   44
4561 
+       UID (fetch result) .........................................   63
4562 
+       UID <message set> (search key) .............................   40
4563 
+       UIDNEXT (status item) ......................................   33
4564 
+       UIDVALIDITY (response code) ................................   51
4565 
+       UIDVALIDITY (status item) ..................................   34
4566 
+       UNANSWERED (search key) ....................................   40
4567 
+       UNDELETED (search key) .....................................   40
4568 
+       UNDRAFT (search key) .......................................   40
4569 
+       UNFLAGGED (search key) .....................................   40
4570 
+       UNKEYWORD <flag> (search key) ..............................   40
4571 
+       UNSEEN (response code) .....................................   51
4572 
+       UNSEEN (search key) ........................................   40
4573 
+       UNSEEN (status item) .......................................   34
4574 
+       UNSUBSCRIBE (command) ......................................   30
4575 
+       Unique Identifier (UID) (message attribute) ................    7
4576 
+       X<atom> (command) ..........................................   48
4577 
+       [RFC-822] Size (message attribute) .........................   11
4578 
+       \Answered (system flag) ....................................    9
4579 
+       \Deleted (system flag) .....................................    9
4580 
+       \Draft (system flag) .......................................    9
4581 
+       \Flagged (system flag) .....................................    9
4582 
+       \Marked (mailbox name attribute) ...........................   54
4583 
+       \Noinferiors (mailbox name attribute) ......................   54
4584 
+       \Noselect (mailbox name attribute) .........................   54
4585 
+       \Recent (system flag) ......................................   10
4586 
+       \Seen (system flag) ........................................    9
4587 
+       \Unmarked (mailbox name attribute) .........................   54
4588 
+
4589 
+
4590 
+
4591 
+
4592 
+
4593 
+
4594 
+Crispin                     Standards Track                    [Page 82]
4595 
+
t-imap.cl
History View file @ 5885760
0 4596 
new file mode 100644
... ... 
@@ -0,0 +1,185 @@
1 
+;; imap testing
2 
+;; requires smtp module too
3 
+
4 
+(eval-when (compile load eval)
5 
+  (require :test))
6 
+
7 
+
8 
+(in-package :test)
9 
+
10 
+
11 
+(defparameter *test-machine* "tiger.franz.com")
12 
+(defparameter *test-account* "jkfmail")
13 
+(defparameter *test-password* "jkf.imap")
14 
+
15 
+
16 
+(defparameter *test-email* (format nil "~a@~a" *test-account* *test-machine*))
17 
+
18 
+
19 
+(defun test-connect ()
20 
+  ;; test connecting and disconnecting from the server
21 
+
22 
+  (let ((mb (mb:make-imap-connection *test-machine*
23 
+				     :user *test-account*
24 
+				     :password *test-password*)))
25 
+    (unwind-protect
26 
+	(progn
27 
+
28 
+	  (test-t (not (null mb)))  ; make sure we got a mailbox object
29 
+
30 
+	  ; check that we've stored resonable values in the mb object
31 
+	  (test-equal "/" (mb:mailbox-separator mb))
32 
+
33 
+	  (test-t (mb::select-mailbox mb "inbox"))
34 
+
35 
+	  (test-t (> (mb:mailbox-uidvalidity mb) 0))
36 
+	  (test-t (not (null (mb:mailbox-flags mb)))))
37 
+
38 
+      (test-t (mb:close-imap-connection mb)))))
39 
+
40 
+
41 
+(defun test-sends ()
42 
+  ;; test sending and reading mail
43 
+  (let ((mb (mb:make-imap-connection *test-machine*
44 
+				     :user *test-account*
45 
+				     :password *test-password*)))
46 
+    (unwind-protect
47 
+	(progn
48 
+	  (test-t (not (null mb)))  ; make sure we got a mailbox object
49 
+
50 
+	  ;; go through the mailboxes and delete all letters
51 
+	  (dolist (mblist (mb:mailbox-list mb :pattern "*"))
52 
+	    (if* (not (member :\\noselect (mb:mailbox-list-flags mblist)))
53 
+	       then (mb:select-mailbox mb (mb:mailbox-list-name mblist))
54 
+		    (let ((count (mb:mailbox-message-count mb)))
55 
+		      ; remove all old mail
56 
+		      (if* (> count 0)
57 
+			 then (mb:alter-flags mb `(:seq 1 ,count) :add-flags :\\deleted)
58 
+			      (mb:expunge-mailbox mb)
59 
+			      (test-eql 0 (mb:mailbox-message-count mb)))
60 
+		      ; remove mailbox (except inbox)
61 
+		      (if* (not (equalp "inbox" (mb:mailbox-list-name mblist)))
62 
+			 then (mb:delete-mailbox mb (mb:mailbox-list-name mblist)))
63 
+
64 
+		      )))
65 
+
66 
+
67 
+	  ;; send five letters
68 
+	  (dotimes (i 5)
69 
+	    (smtp:send-smtp *test-machine*
70 
+			    *test-email*
71 
+			    *test-email*
72 
+			    (format nil "message number ~d" (1+ i))))
73 
+
74 
+	  ; test to see if imap figures out that the letters are there
75 
+	  (mb:select-mailbox mb "inbox")
76 
+
77 
+	  ; wait a bit for the mail to be delivered
78 
+	  (dotimes (i 5)
79 
+	    (if* (not (eql 5 (mb:mailbox-message-count mb)))
80 
+	       then (sleep 1)
81 
+		    (mb: noop mb)))
82 
+
83 
+	  (test-eql 5 (mb:mailbox-message-count mb))
84 
+
85 
+	  ; test the search facility
86 
+	  ; look for the message number we put in each message.
87 
+	  ; I hope the letters get delivered in order...
88 
+	  (dotimes (i 5)
89 
+	    (let ((mn (1+ i)))
90 
+	      (test-equal (list mn)
91 
+			  (mb:search-mailbox mb
92 
+					     `(:body ,(format nil "~d" mn))))))
93 
+
94 
+	  ; test getting data from mail message
95 
+	  (let ((fetch-info (mb:fetch-letter mb
96 
+					   1
97 
+					   "(envelope body[1])")))
98 
+	    (let ((envelope (mb:fetch-field 1 "envelope" fetch-info))
99 
+		  (body (mb:fetch-field 1 "body[1]" fetch-info)))
100 
+	      (test-equal "jkfmail" (mb:address-mailbox
101 
+				     (car (mb:envelope-from envelope))))
102 
+	      (test-nil (mb:address-mailbox
103 
+			 (car (mb:envelope-to envelope))))
104 
+
105 
+	      (test-equal (format nil "message number 1~c" #\newline)
106 
+			  body))))
107 
+      (test-t (mb:close-imap-connection mb)))))
108 
+
109 
+
110 
+
111 
+(defun test-flags ()
112 
+  ;; test setting and getting flags
113 
+  ;;
114 
+  ;; assume we have 5 messages in inbox at this time
115 
+  ;;
116 
+  (let ((mb (mb:make-imap-connection *test-machine*
117 
+				     :user *test-account*
118 
+				     :password *test-password*)))
119 
+    (unwind-protect
120 
+	(progn
121 
+	  (mb:select-mailbox mb "inbox")
122 
+
123 
+	  (let ((flags (mb:fetch-field 3
124 
+				       "flags"
125 
+				       (mb:fetch-letter
126 
+					mb 3 "flags"))))
127 
+	    (test-nil flags))
128 
+
129 
+	  ;; add flags
130 
+	  (let ((info (mb:alter-flags mb 3 :add-flags :\\deleted)))
131 
+	    (test-equal '(:\\deleted)
132 
+			(mb:fetch-field 3 "flags" info)))
133 
+
134 
+	  ; good bye message
135 
+	  (test-equal '(3) (mb:expunge-mailbox mb))
136 
+
137 
+	  (mb:alter-flags mb 4 :add-flags ':\\bbbb)
138 
+	  (test-equal '(:\\bbbb)
139 
+		      (mb:fetch-field 4 "flags"
140 
+				      (mb:fetch-letter mb 4
141 
+						       "flags")))
142 
+
143 
+
144 
+	  )
145 
+      (test-t (mb:close-imap-connection mb)))))
146 
+
147 
+(defun test-mailboxes ()
148 
+  ;; should be 4 messages now in inbox
149 
+  ;; let's create 4 mailboxes, one for each letter
150 
+  (let ((mb (mb:make-imap-connection *test-machine*
151 
+				     :user *test-account*
152 
+				     :password *test-password*)))
153 
+    (unwind-protect
154 
+	(progn
155 
+	  (mb:select-mailbox mb "inbox")
156 
+	  (dotimes (i 4)
157 
+	    (let ((mbname (format nil "temp/mb~d" i)))
158 
+	      (test-t (mb:create-mailbox mb mbname))
159 
+	      (mb:copy-to-mailbox mb (1+ i) mbname)))
160 
+
161 
+	  ; now check that each new mailbox has one message
162 
+	  (dotimes (i 4)
163 
+	    (let ((mbname (format nil "temp/mb~d" i)))
164 
+	      (mb:select-mailbox mb mbname)
165 
+	      (test-eql 1 (mb:mailbox-message-count mb)))))
166 
+      (test-t (mb:close-imap-connection mb)))))
167 
+
168 
+(defun test-imap ()
169 
+  (test-connect)
170 
+
171 
+  (test-sends)
172 
+
173 
+  (test-flags)
174 
+
175 
+  (test-mailboxes)
176 
+
177 
+  )
178 
+
179 
+
180 
+(if* *do-test* then (do-test :imap #'test-imap))
181 
+
182 
+
183 
+
184 
+
185 
+