The intent of this document is to describe every aspect of nnimap at the user level. This document corresponds to nnimap 0.123.
Please note that nnimap require that you use the latest Gnus series, called Pterodactyl Gnus.
Also note that nnimap isn't so much different from other backends in Gnus, so this documentation sort of assumes that you're familiar with basic concepts in Gnus.
To use nnimap, you should
Once you've done that, you can use nnimap. (see section Using nnimap)
We've collected some neat tricks, several which aren't nnimap specific, we've found useful when using nnimap. (see section Neat tricks)
To join the mailing list, send a message to nnimap-request@extundo.com. In the body of the message put
subscribe
The latest version of this nnimap implementation is always available as
http://josefsson.org/nnimap/nnimap.tar.gz
Download the archive and unpack it.
$ tar xfz nnimap.tar.gz
This will create a directory such as `nnimap-0.123/' which contain all files.
Compile it by issuing the following commands:
$ cd nnimap-0.123 $ make GNUSDIR=~/elisp/pgnus-0.88/lisp
If you use XEmacs, use
$ cd nnimap-0.123 $ make GNUSDIR=~/elisp/pgnus-0.88/lisp EMACS=xemacs
instead.
Please note that you need to specify where Gnus is installed with GNUSDIR for nnimap to find the base64 and md5 libraries.
You now need to tell Emacs about nnimap. This is done by editing `~/.emacs'. Put something similar to this:
(setq load-path
(cons (expand-file-name "~/elisp/nnimap-0.123") load-path))
(require '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. (The excellent Gnus manual has a section on the server buffer if you really want to know.)
To tell Gnus 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-address "cyrus.andrew.cmu.edu")
(nnimap-authenticator anonymous)
(nnimap-list-pattern ("INBOX" "archive.*")))
(nnimap "yoyo"
(nnimap-stream ssl)
(nnimap-address "your.mail.server"))))
The server variables used above are explained later on.
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 at http://andrew2.andrew.cmu.edu/cyrus/cyrustest.html.)
Tired of telling nnimap about your username/password all the time? The New and Improved Gnus, Gnus series 5.6.x and later that is, can do this for you.
Unfortunately, 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
Unfortunely there is no known way to have a login/password containing space.
nnimap-addressHostname or IP address of IMAP server to use. Defaults to the Gnus server name ("dada" and "yoyo" in the examples above) unless specified.
nnimap-server-portPort on server to contact. Defaults to port 143, or 993 for SSL.
nnimap-list-patternString 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 University of Washington server you want to limit the mailboxes to those 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 University of Washington server you can specify the directory to use. Another example:
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-address "mail.server")
(nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*"))))))
nnimap-streamThis server variable let you change the type of stream used to connect to your server. If unset, nnimap will use the most secure stream your server is capable of.
You would want to change this from the default for two reasons:
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-address "mail.server")
(nnimap-stream ssl))))
nnimap-authenticatorThis server variable let you change the authenticator used to connect to the server. If unset, nnimap will use the most secure authenticator your server is capable of.
There is only one reason for fiddling with this variable, and that is if your server is more capable than your environment -- i.e. you connect to a server that accept Kerberos login's but you haven't installed the `imtest' program or your machine isn't configured for Kerberos.
Example:
(setq gnus-secondary-select-methods
'((nnimap "nana"
(nnimap-address "mail.server")
(nnimap-authenticator anonymous))))
nnimap-expunge-on-closeUnlike Parmenides the IMAP designers has decided that things that doesn't exist actually does exist. More specifically, IMAP has this concept of marking articles "Deleted" which doesn't actually delete them, and this (marking them "Deleted", that is) is what nnimap does when you delete a article in Gnus (with `G d' or similair).
Since the articles aren't really removed when we mark them with the "Deleted" flag we'll need a way to actually delete them. Feel like running in circles yet?
Traditionally, nnimap has removed all articles marked as "Deleted" when closing a mailbox but this is now configurable by this server variable.
The possible options are:
always
never
ask
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.
There are three variables of interest:
nnimap-split-crosspost
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.
nnimap-split-inboxA 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.
nnimap-split-rule
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.nnimap" "^Sender: owner-nnimap@vic20.globalcom.se")
("INBOX.spam" "^Subject:.*MAKE MONEY")
("INBOX.private" "")))
This will put all articles from the nnimap mailing list into mailbox INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line into INBOX.spam and everything else in INBOX.private.
The first string may contain `\\1' forms, like the ones used by replace-match to insert sub-expressions from the matched text. For instance:
("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@")
The second element can also be a function. In that case, it will be called with the first element of the rule as the argument, in a buffer containing the headers of the article. It should return a non-nil value if it thinks that the mail belongs in that group.
Nnmail users might recollect that the last regexp had to be empty to match all articles (like in the example above). This is not required in nnimap. Articles not matching any of the regexps will not be moved out of your inbox. (This might might affect performance if you keep lots of unread articles in your inbox, since the splitting code would go over them every time you fetch new mail.)
These rules are processed from the beginning of the alist toward the end. The first rule to make a match will "win", unless you have crossposting enabled. In that case, all matching rules will "win".
The splitting code tries to create mailboxes if it need too.
Nnmail equivalent: nnmail-split-methods.
Expiring in nnimap works just like it does in the nnmail backends.
That is, you either mark articles for expiring manually, or use
gnus-auto-expirable-newsgroups variable, or the
auto-expire, total-expire group parameters (or any other
way you can think of).
To hopefully not confuse things (but possibly confuse things further),
nnimap has decided to use the nnmail-expiry-wait and
nnmail-expiry-wait-function variables to configure the expiring
process. So you would only need to tinker with the
gnus-auto-expirable-newsgroups regexp to include nnimap folders,
or set the auto-expire, total-expire group parameters on
nnimap folders to enable expiring.
(The reasoning behind the decision to use nnmail variables instead of
defining `nnimap-expiry-wait' is that `nnmail-expiry-wait' are set by
Gnus when you customize the expiry-wait group parameter.)
For Kerberos authentication and encryption you need to have the external
program imtest which comes with Cyrus IMAPD
(http://andrew2.andrew.cmu.edu/cyrus/) in your path.
Also see the documentation on variables imap-imtest-program if
you want to use a different program and/or switches than the default.
For SSL encryption you need to have either SSLeay (s_client),
http://www.ssleay.org/, or OpenSSL (openssl),
http://www.openssl.org/ installed.
Also see the documentation on variables imap-ssl-program and
imap-ssl-arguments if you need to change the details.
Nnimap has a detailed logging/debugging capability, most are by default turned on. These are controlled by three variables. If you set the variable to nil you're disabling it (things will go faster but you'll be unable to make good bug reports).
imap-log
*imap-log*.
imap-debug
nnimap-debug
*nnimap-debug*.
So now what? You've started your Gnus, and there is nothing other than all that mail you keep telling yourself you will read tomorrow? No free beer, 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 section Installing nnimap.)
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 Meta-g on the group (in the group buffer) to force a new mail fetch (which also updates all marks).
Even after g (or Meta-g), Gnus may show that you have an enormous 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 nonexistent 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 List. ACLs 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:
If you're using the `never' nnimap-expunge-close setting, you may
want the option of expunging all deleted articles in a mailbox manually
sometimes.
Jump to the group, in the group buffer, you wish to run the EXPUNGE command in and type `G x', it will complain if you're not standing over a nnimap group.
Currently there is no way of showing deleted articles.
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 convenience:
(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 can't trust anyone. After a little work 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. See section Automatic logins using ~/.authinfo.
Nnimap has solved this problem by letting you use, instead of the server address, the virtual Gnus server name when specifying username/passwords in the authinfo file. I think a example will tell you what you need to do:
Example, `~/.authinfo' file:
machine server1 login user1 password pw1 machine server2 login user2 password pw2 machine server3 login user3 password pw3 machine server4 login anonymous password foo@bar.org
And your `~/.gnus' would contain something like:
(setq gnus-secondary-select-methods
'((nnimap "server1"
(nnimap-address "localhost")
(nnimap-server-port 4711))
(nnimap "server2"
(nnimap-address "localhost")
(nnimap-server-port 4712))
(nnimap "server3"
(nnimap-stream ssl)
(nnimap-address "localhost")
(nnimap-server-port 4713))
(nnimap "server4"
(nnimap-address "localhost"))
(nnimap-server-port 4713)))
Note also that in this example you have two server connections open to localhost:4713, one as user3 over a SSL connection and one anonymous login using the auto-detect stream / authenticator method.
Now you should be able to connect to your IMAP server securely to read your mail, which, by the way, has been sent in clear-text through the entire internet.
Bug reports are highly appreciated of course. When debugging a problem
it's very useful to be able to see the content of your *imap-log*
and *nnimap-debug* buffers.
A good way to generate debug buffers containing relevant information is to start your gnus, kill your debug buffers and perform whatever tasks to trigger the bug. Save your buffers and mail'em of to the nnimap mailing list.
Numerous people have helped the nnimap project, here I list people who have written code, sent bug reports and other things. Apologies to everybody I've forgotten.
John Prevost, Jim Radford, Marty Fouts, Jake Colman, Jeff Senn, Trung Tran-Duc, Matt Armstrong, Keisuke Mori, Daiki Ueno, Jon K Hellan, Donald Hunter
Jump to: a - c - d - e - f - g - i - k - m - n - p - r - s - u
Jump to: a - e - g - i - n - t
This document was generated on 12 September 1999 using texi2html 1.56k.