The intent of this document is to describe every aspect of nnimap at the user level.
The latest version of this nnimap implementation is always available as http://vic20.dzp.se/gnus-imap/nnimap.tar.gz.
Download the archive and unpack it.
host$ tar xfz nnimap.tar.gz
This will create a directory nnimap-X/ which contain all files. X is the current version number.
Compile it by issuing the following commands:
$ cd nnimap-0.3.11 $ make
If you use XEmacs, use make EMACS=xemacs instead.
You now need to tell Emacs about nnimap. This is done by editing ~/.emacs. Put the following in the file:
(setq load-path
(cons (expand-file-name "~/elisp/nnimap-0.3.11") load-path))
(require 'nnimap)
Replace ~/elisp/nnimap-0.3.11 with the directory name created when you untared nnimap.
(You could put this in ~/.gnus instead if you like.)
Fire up Gnus and you should be able to tinker with nnimap in the server buffer. If you aren't familiar with the server buffer, never mind you wont miss anything. (Ok, ok, the excellent Gnus manual has a section on the server buffer if you want to know.)
To tell nnimap about your IMAP servers, you have to modify gnus-secondary-select-methods (or maybe, gnus-select-method) in your ~/.gnus.
The following describes a situation where you would have a nnfolder server (perhaps for storing old personal mail you don't want to store online?) and two nnimap servers.
(setq gnus-secondary-select-methods
'((nnfolder "")
(nnimap "dada"
(nnimap-server-address "cyrus.andrew.cmu.edu")
(nnimap-list-pattern ("INBOX" "archive.*")))
(nnimap "yoyo"
(nnimap-server-address "your.mail.server"))))
Now when Gnus starts, it will ask you for a username/password for each IMAP server.
(For information about the cyrus public IMAP server, there is more information available.)
Description of server variables:
First, as shown in the example, limiting the number of mailboxes you're interested in on a server with very many mailboxes.
Secondly but related, if using the UW server you want to limit the mailboxes to thoose in ~/Mail/* for instance.
The string can also be a cons of REFERENCE and the string as above, what REFERENCE is used for is server specific, but on the UWash server you can specify the directory to use. Another example:
("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*"))
For Kerberos authentication and encryption you need to have the external program "imtest" (comes with some IMAP server?? I dunno) in your path, and also add the following to ~/.gnus:
(setq-default imap-open-stream 'imap-open-imtest-stream)
For SSL encryption you need to have the external program "s_client" (comes with SSLeay) in your path, and also add the following to ~/.gnus:
(setq-default imap-open-stream 'imap-open-ssl-stream)
Note! If you get SSL to work, please send me a note! I have not been able to verify that this work.
So now what? You've started your Gnus, and there is nothing other than all those mail you keep telling yourself you will read tomorrow? No free beers, no world peace, no nothing. Ahem, afraid so, it's scheduled to be in version 1.0 though.
To access IMAP mailboxes you need to subscribe to them. Use 'U' (gnus-group-unsubscribe-group) in the Group buffer and use command completion to show what mailboxes are available. If you want to subscribe to many mailboxes or want a somewhat fancier look of your mailboxes, you should really learn how to use the server buffer (see the install section).
After subscribing to one or more mailboxes you found interesting Gnus will show that you haven't read any mail at all in that group. Gnus is only guessing the first time, so press 'M-g' on the group (in the group buffer) to force a new mail fetch (which also updates all marks).
Even after 'g' (or 'M-g'), Gnus may show that you have an enourmus amount of unread mail in that group. This is because Gnus is only making an estimate of how many articles are in group, and it makes this estimate by calculating HIGH-LOW+1, where HIGH is the article number of the latest article and LOW is article number of the oldest article. To possibly correct this, enter (SPC or RET) and exit the group ('q'). This will mark all nonexistant articles as read (an oddity in Gnus, you don't want to know). There could still be problems, currently you'll have to live with this. Please report what server you are using and exactly what problems you see, so I'm aware if this is a big problem for many people.
That's it. You should now be able to use the group as any other group.
ACL stands for Access Control Lists and are used for limiting (or enabling) other users access to your mail boxes. Not all server support this, you'll find out if your server does when you try to use this function.
To edit a group's ACL, move the cursor in the Group buffer to a nnimap Group and type G l (gnus-group-edit-nnimap-acl) to have it jump to the ACL editor. The instructions presented in that buffer should get you going.
Some possible uses:
Splitting is something Gnus users has loved and used for years, and now the rest of the world is catching up. Yeah, dream on, not many IMAP server has server side splitting and those that have splitting seem to use some non-standard protocol. This means that IMAP support for Gnus has to do it's own splitting.
And it does.
Warning! This is stuff that will change in the coming releases of nnimap. Actually, this goes for anything in this document, I will not try to be backwards compatible at all.
There are three variables of interest:
If non-nil, do crossposting if several split methods match the mail. If nil, the first match in nnimap-split-rule found will be used.
(setq nnimap-split-crosspost t)
Nnmail equivalent: nnmail-crosspost.
A string or a list of strings that gives the name(s) of IMAP mailboxes to read mail from and split according the the split rule. Defaults to nil, which means that splitting is disabled!
(setq nnimap-split-inbox '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
No nnmail equivalent.
New mail found in nnimap-split-inbox will be split according to this variable.
This variable contains a list of lists, where the first element in the sublist gives the name of the IMAP mailbox to move articles matching the regexp in the second element in the sublist. Got that? Neither did I, we need examples.
(setq nnimap-split-rule
'(("INBOX.gnus-imap" "^Sender: owner-gnus-imap@vic20.dzp.se")
("INBOX.spam" "^Subject:.*MAKE MONEY")
("INBOX.private" "")))
This will put all articles from the gnus-imap mailing list into the IMAP mailbox INBOX.gnus-imap, all articles containing MAKE MONEY in the Subject: line in INBOX.spam and everything else in INBOX.private.
It's probably a very good idea to have a empty regexp as the last entry has in the example, this will clear the incoming mailbox from mail that otherwise would be subject to the splitting process every time you start Gnus.
The splitting code tries to create mailboxes if it has too.
Nnmail (semi-)equivalent: nnmail-split-methods.
You want something to watch while you wait for nnimap to do it's work?
(setq gnus-verbose 9)
You could try 10 too, then you will see every IMAP command sent to the server. A little bit too noisy IMHO.
The default is 7.
The number of lines are showed in the summary buffer, yes, but the octet count can be interesting too. I use the following:
(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-20,20n%]%) (%c) %s\n")
I've added the " (%c)" part at the end of the string.