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.
$ 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-auth-method cram-md5)
(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.)
Tired of telling nnimap about your username/password all the time? The New and Improved Gnus, Gnus series 5.6.x that is, can do this for you.
Unfortunely, you still have to tell it your username/password once. Whee, what a bugger. A bigger bugger (huh?) however is that you have to store the password clear-text in a file. Depending on your level of paranoia you may or may not want to do this.
Anyway, nnimap looks for a file ~/.authinfo (nnimap-authinfo-file) which contains the username/password. This file follows the old "netrc" format.
Example ~/.authinfo file:
machine mail.server login arne password aDd12xX1 default login anonymous password arne@domain.org
Hostname or IP address of IMAP server to use. Defaults to the Gnus server name ("dada" and "yoyo" in the examples above) unless specified.
When listing mailboxes on the server, the IMAP protocol has two commands. "LIST", the default in nnimap, lists all mailboxes (limited by nnimap-list-pattern). "LSUB" lists all subscribed mailboxes.
Currently nnimap does not support server side subscribing/unsubscribing so the natural choice is "LIST". However, if you have subscribed to interesting mailboxes using another IMAP client you could take advantage of this selection by telling nnimap to use it.
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-server-address "mail.server")
(nnimap-list-method "LSUB"))))
String or list of strings of mailboxes to limit available groups to. This has two uses.
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:
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-server-address "mail.server")
(nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*"))))))
This server variable let's you change the login scheme used for the server.
Valid options are:
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-server-address "mail.server")
(nnimap-auth-method kerberos4))))
For Kerberos authentication and encryption you need to have the external program "imtest" (comes with Cyrus IMAPD) in your path.
For SSL encryption you need to have the external program "s_client" (comes with SSLeay) in your path.
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.
Are you using nnimap from home, over a dialup connection? Then maybe "Article Caching", another Gnus feature, is for you.
You should really read the Gnus manual on Article Caching to get the whole picture, but here is a simple setup for your convinience:
(setq gnus-use-cache t) (setq gnus-cache-directory "~/Mail/cache/") (setq gnus-cache-enter-articles '(ticked dormant read unread)) (setq gnus-cache-remove-articles nil) (setq gnus-cacheable-groups "^nnimap")
Scenario: You want to connect to multiple IMAP servers. You've seen the X Files so you know you can't trust anyone, so you've written your own privacy/encryption suite. Using it, you've securely forwarded the connections to your IMAP servers and have them available on localhost:4711, localhost:4712, localhost:4713 and so on.
So what's the problem? Just add them to your gnus-secondary-select-method just as any other servers. But of course, this works.
However, if you want to use automatic logins using a ~/.authinfo file you'll find out that this file format doesn't support multiple services on the same host.
Nnimap has solved this problem by introducing something called a "port-extended" format. I think a example will tell you what you need to do:
Example, ~/.authinfo file:
machine localhost:4711 login user1 password pw1 machine localhost:4712 login user2 password pw2 machine localhost:4713 login user3 password pw3
And your ~/.gnus would contain something like:
(setq gnus-secondary-select-methods
'((nnimap "srv1"
(nnimap-server-address "localhost:4711"))
(nnimap "srv2"
(nnimap-server-address "localhost:4712"))
(nnimap "srv3"
(nnimap-server-address "localhost:4713"))))
Now you should be able to connect to your IMAP server securly to read your mail, which, by the way, has been sent in clear-text through the entire internet.