Installation, configuration and usage instructions for nnimap

by Simon Josefsson

Table of Contents


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

  1. Join the mailing list (see section nnimap mailing list.)
  2. Download, unpack and compile a recent version. (see section Downloading, unpacking and compiling nnimap)
  3. Install that version in your `.emacs'. (see section Installing nnimap)
  4. Configure it for your server and mailboxes. (see section Configuring nnimap)

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)

nnimap mailing list.

To join the mailing list, send a message to In the body of the message put


Downloading, unpacking and compiling nnimap

The latest version of this nnimap implementation is always available as

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


Please note that you need to specify where Gnus is installed with GNUSDIR for nnimap to find the base64 and md5 libraries.

Installing nnimap

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.)

Configuring nnimap

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 "")
                (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

Automatic logins using ~/.authinfo

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

Unfortunely there is no known way to have a login/password containing space.

Server variables


Hostname or IP address of IMAP server to use. Defaults to the Gnus server name ("dada" and "yoyo" in the examples above) unless specified.


Port on server to contact. Defaults to port 143, or 993 for SSL.


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 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:


(setq gnus-secondary-select-methods 
      '((nnimap "nana"
		(nnimap-address "mail.server")
                (nnimap-list-pattern ("INBOX" "Mail/*" "*" ("~friend/Mail/" . "list/*"))))))


This 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:


(setq gnus-secondary-select-methods 
      '((nnimap "nana"
		(nnimap-address "mail.server")
                (nnimap-stream ssl))))


This 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.


(setq gnus-secondary-select-methods 
      '((nnimap "nana"
		(nnimap-address "mail.server")
                (nnimap-authenticator anonymous))))


Unlike 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:

The default behaviour, delete all articles marked as "Deleted" when closing a mailbox.
Never actually delete articles. Currently there is no way of showing the articles marked for deletion in nnimap, but other IMAP clients may allow you to do this. If you ever want to run the EXPUNGE command manually, See section "Compress mailbox".
When closing mailboxes, nnimap will ask if you wish to expunge deleted articles or not.

Splitting Mail

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:


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.nnimap"        "^Sender:")
          ("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 Mail

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.)

Required programs for kerberos

For Kerberos authentication and encryption you need to have the external program imtest which comes with Cyrus IMAPD ( 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.

Required programs for ssl

For SSL encryption you need to have either SSLeay (s_client),, or OpenSSL (openssl), 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).

Contains name of buffer to hold the log of IMAP conversation between nnimap and the IMAP server. It defaults to *imap-log*.
Contains name of buffer to hold elisp tracing of the imap library. Defaults to nil.
Contains name of buffer to hold elisp tracing of nnimap. Defaults to *nnimap-debug*.

Using nnimap

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.

Editing ACLs

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:

"Compress mailbox"

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.

Neat tricks

Getting verbose information

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.

Showing article length in the summary buffer

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.

Article caching

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")

Authinfo logins against multi-port servers

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

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.

Reporting bugs

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

Concept Index

Jump to: a - c - d - e - f - g - i - k - m - n - p - r - s - u


  • Access Control Lists
  • anonymous
  • Article caching
  • article length, octets
  • Auhtorization method
  • Authentication, kerberos, Authentication, kerberos
  • authinfo
  • authinfo logins against multi-port servers
  • Automatic logins using ~/.authinfo
  • c

  • caching
  • Closing mailboxes
  • Compiling nnimap
  • Configuring nnimap
  • Configuring splitting
  • Configuring the server(s)
  • crosspost
  • Customizing nnimap
  • d

  • debugging nnimap
  • Downloading nnimap
  • e

  • Editing ACLs
  • expiring
  • Expunge
  • Expunging
  • f

  • Finding mailboxes
  • g

  • Getting nnimap
  • Getting verbose information
  • i

  • inbox
  • Installing nnimap
  • k

  • kerberos
  • m

  • mail splitting
  • Mailbox regexp
  • mailing list
  • Manual expunging
  • multiple servers
  • n

  • Network streams
  • p

  • Password configuration
  • r

  • running nnimap
  • s

  • Selecting mailboxes
  • Server Address
  • Server port
  • Server variables
  • servers, multiple
  • Showing article length in the summary buffer
  • splitting
  • splitting, crosspost
  • splitting, inbox
  • Splitting, rules
  • ssl
  • summary buffer length
  • u

  • Unpacking nnimap
  • Username configuration
  • using kerberos
  • using nnimap
  • using ssl
  • Variable and Function Index

    Jump to: a - e - g - i - n - t


  • auto-expire
  • e

  • expire-wait
  • g

  • gnus-auto-expirable-newsgroups
  • gnus-cache-enter-articles
  • gnus-cache-remove-articles
  • gnus-cacheable-groups
  • gnus-secondary-select-methods, gnus-secondary-select-methods
  • gnus-select-method
  • gnus-summary-line-format
  • gnus-use-cache
  • gnus-verbose
  • i

  • imap-debug
  • imap-imtest-program
  • imap-log
  • imap-ssl-arguments
  • imap-ssl-program
  • n

  • nnimap-address
  • nnimap-authenticator
  • nnimap-authinfo-file
  • nnimap-debug
  • nnimap-expunge-on-close
  • nnimap-list-pattern
  • nnimap-server-port
  • nnimap-split-crosspost
  • nnimap-split-inbox
  • nnimap-split-rule
  • nnimap-stream
  • nnmail-expiry-wait
  • nnmail-expiry-wait-function
  • t

  • total-expire

  • This document was generated on 12 September 1999 using texi2html 1.56k.