How does imap.el work?

[Philippe M . Coatmeur]

Hi ; I'm trying to understand how to use imap.el (part of GNU emacs,
I'm using 24.1.50) and got it to do pretty nifty tricks, like 

-Connect to my imap server (both my own dovecot and gmail)
-List mailboxes and select one
-List sub-mailboxes in said selected mailbox
-Get a message by it id

(see a glimpse of my experiments at the end of this message)

But what I really want to do is get a list of unread (IMAP flag
"UNSEEN") mails. Now on top of the lib, in the comments, is a list of
all available commands :

;; Global commands:
;;
;; imap-open,       imap-opened,    imap-authenticate, imap-close,
;; imap-capability, imap-namespace, imap-error-text
;;
;; Mailbox commands:
;;
;; imap-mailbox-get,       imap-mailbox-map,         imap-current-mailbox,
;; imap-current-mailbox-p, imap-search,              imap-mailbox-select,
;; imap-mailbox-examine,   imap-mailbox-unselect,    imap-mailbox-expunge
;; imap-mailbox-close,     imap-mailbox-create,      imap-mailbox-delete
;; imap-mailbox-rename,    imap-mailbox-lsub,        imap-mailbox-list
;; imap-mailbox-subscribe, imap-mailbox-unsubscribe, imap-mailbox-status
;; imap-mailbox-acl-get,   imap-mailbox-acl-set,     imap-mailbox-acl-delete
;;
;; Message commands:
;;
;; imap-fetch-asynch,                 imap-fetch,
;; imap-current-message,              imap-list-to-message-set,
;; imap-message-get,                  imap-message-map
;; imap-message-envelope-date,        imap-message-envelope-subject,
;; imap-message-envelope-from,        imap-message-envelope-sender,
;; imap-message-envelope-reply-to,    imap-message-envelope-to,
;; imap-message-envelope-cc,          imap-message-envelope-bcc
;; imap-message-envelope-in-reply-to, imap-message-envelope-message-id
;; imap-message-body,                 imap-message-flag-permanent-p
;; imap-message-flags-set,            imap-message-flags-del
;; imap-message-flags-add,            imap-message-copyuid
;; imap-message-copy,                 imap-message-appenduid
;; imap-message-append,               imap-envelope-from
;; imap-body-lines
;;
;; It is my hope that these commands should be pretty self
;; explanatory for someone that know IMAP.  All functions have
;; additional documentation on how to invoke them.

But no, not "All functions have additional documentation on how to
invoke them.", only a handful have. Go ahead, try to C-h f with point
over imap-mailbox-get, or imap-search.

It also says "these commands should be pretty self explanatory for
someone that know IMAP" and that is right, I don't *know* IMAP like I
know, say my daughter. But still, I implemented two (basic) imap
> clients before, one in PHP and one in Perl (using Mail::IMAPClient)
but both provided thicker abstraction layers than what imap.el does.

I also read http://www.dovecot.org/imap-client-coding-howto.html and
http://www.imapwiki.org/ClientImplementation but again, I miss the
link between those server commands and client implementation.

If anybody know how to get a list of unread messages in a given
mailbox, a "message" being the timestamp, the "from" and the "subject"
using imap.el it would really point me in the right direction...

APPENDIX : Tries

(require 'imap)

(defun my-test-imap ()
  (switch-to-buffer (imap-open "mail.server.net"))
  (with-current-buffer (current-buffer)
    (imap-authenticate "user" "passwd")
    (setq mailbox (imap-mailbox-list "INBOX"))
    (imap-mailbox-select "Inbox")
    (imap-mailbox-get 'uidvalidity)                     ;; Returns nothing
    (setq status (imap-mailbox-status "Inbox" 'unseen)) ;; Returns even less
    (imap-mailbox-examine "Inbox")                      ;; This does nothing too
    (imap-search "ALL")                                 ;; Everything else works
    (setq my-msg (imap-fetch 1 "RFC822" 'RFC822))
    (message "HOY! %s" my-msg)
    (imap-close)
))

(defun test-imap-cmd ()
(interactive)
(test-imap))

Philippe