6.5 IMAP

IMAP is a network protocol for reading mail (or news, or ...), think of it as a modernized NNTP. Connecting to a IMAP server is much similar to connecting to a news server, you just specify the network address of the server.

IMAP has two properties. First, IMAP can do everything that POP can, it can hence be viewed as a POP++. Secondly, IMAP is a mail storage protocol, similar to NNTP being a news storage protocol--however, IMAP offers more features than NNTP because news is more or less read-only whereas mail is read-write.

If you want to use IMAP as a POP++, use an imap entry in mail-sources. With this, Gnus will fetch mails from the IMAP server and store them on the local disk. This is not the usage described in this section---See section 6.3.4 Mail Sources.

If you want to use IMAP as a mail storage protocol, use an nnimap entry in gnus-secondary-select-methods. With this, Gnus will manipulate mails stored on the IMAP server. This is the kind of usage explained in this section.

A server configuration in `~/.gnus.el' with a few IMAP servers might look something like the following. (Note that for TLS/SSL, you need external programs and libraries, see below.)

(setq gnus-secondary-select-methods
      '((nnimap "simpleserver") ; no special configuration
        ; perhaps a ssh port forwarded server:
        (nnimap "dolk"
                (nnimap-address "localhost")
                (nnimap-server-port 1430))
        ; a UW server running on localhost
        (nnimap "barbar"
                (nnimap-server-port 143)
                (nnimap-address "localhost")
                (nnimap-list-pattern ("INBOX" "mail/*")))
        ; anonymous public cyrus server:
        (nnimap "cyrus.andrew.cmu.edu"
                (nnimap-authenticator anonymous)
                (nnimap-list-pattern "archive.*")
                (nnimap-stream network))
        ; a ssl server on a non-standard port:
        (nnimap "vic20"
                (nnimap-address "vic20.somewhere.com")
                (nnimap-server-port 9930)
                (nnimap-stream ssl))))

After defining the new server, you can subscribe to groups on the server using normal Gnus commands such as U in the Group Buffer (see section 2.4 Subscription Commands) or via the Server Buffer (see section 6.1 Server Buffer).

The following variables can be used to create a virtual nnimap server:

nnimap-address

The address of the remote IMAP server. Defaults to the virtual server name if not specified.

nnimap-server-port

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

Note that this should be an integer, example server specification:

(nnimap "mail.server.com" (nnimap-server-port 4711))

nnimap-list-pattern

String or list of strings of mailboxes to limit available groups to. This is used when the server has very many mailboxes and you're only interested in a few--some servers export your home directory via IMAP, you'll probably want to limit the mailboxes to those in `~/Mail/*' then.

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 it's a directory that will be concatenated with the mailbox.

Example server specification:

(nnimap "mail.server.com" (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" ("~friend/Mail/" . "list/*"))))

nnimap-stream

The type of stream used to connect to your server. By default, nnimap will detect and automatically use all of the below, with the exception of TLS/SSL. (IMAP over TLS/SSL is being replaced by STARTTLS, which can be automatically detected, but it's not widely deployed yet.)

Example server specification:

(nnimap "mail.server.com" (nnimap-stream ssl))

Please note that the value of nnimap-stream is a symbol!

• gssapi: Connect with GSSAPI (usually Kerberos 5). Requires the `gsasl' or `imtest' program.
• kerberos4: Connect with Kerberos 4. Requires the `imtest' program.
• starttls: Connect via the STARTTLS extension (similar to TLS/SSL). Requires the external library `starttls.el' and program `starttls'.
• tls: Connect through TLS. Requires GNUTLS (the program `gnutls-cli').
• ssl: Connect through SSL. Requires OpenSSL (the program `openssl') or SSLeay (`s_client').
• shell: Use a shell command to start IMAP connection.
• network: Plain, TCP/IP network connection.

The `imtest' program is shipped with Cyrus IMAPD. If you're using `imtest' from Cyrus IMAPD < 2.0.14 (which includes version 1.5.x and 1.6.x) you need to frob imap-process-connection-type to make imap.el use a pty instead of a pipe when communicating with `imtest'. You will then suffer from a line length restrictions on IMAP commands, which might make Gnus seem to hang indefinitely if you have many articles in a mailbox. The variable imap-kerberos4-program contain parameters to pass to the imtest program.

For TLS connection, the gnutls-cli program from GNUTLS is needed. It is available from http://www.gnu.org/software/gnutls/.

This parameter specifies a list of command lines that invoke a GSSAPI authenticated IMAP stream in a subshell. They are tried sequentially until a connection is made, or the list has been exhausted. By default, `gsasl' from GNU SASL, available from http://www.gnu.org/software/gsasl/, and the `imtest' program from Cyrus IMAPD (see imap-kerberos4-program), are tried.

For SSL connections, the OpenSSL program is available from http://www.openssl.org/. OpenSSL was formerly known as SSLeay, and nnimap support it too--although the most recent versions of SSLeay, 0.9.x, are known to have serious bugs making it useless. Earlier versions, especially 0.8.x, of SSLeay are known to work. The variable imap-ssl-program contain parameters to pass to OpenSSL/SSLeay.

For IMAP connections using the shell stream, the variable imap-shell-program specify what program to call. Make sure nothing is interfering with the output of the program, e.g., don't forget to redirect the error output to the void.

nnimap-authenticator

The authenticator used to connect to the server. By default, nnimap will use the most secure authenticator your server is capable of.

Example server specification:

(nnimap "mail.server.com" (nnimap-authenticator anonymous))

Please note that the value of nnimap-authenticator is a symbol!

• gssapi: GSSAPI (usually kerberos 5) authentication. Requires external program gsasl or imtest.
• kerberos4: Kerberos 4 authentication. Requires external program imtest.
• digest-md5: Encrypted username/password via DIGEST-MD5. Requires external library digest-md5.el.
• cram-md5: Encrypted username/password via CRAM-MD5.
• login: Plain-text username/password via LOGIN.
• anonymous: Login as "anonymous", supplying your email address as password.

nnimap-expunge-on-close

Unlike Parmenides the IMAP designers have decided things that don't exist actually do 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 an article in Gnus (with B DEL or similar).

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

The default behavior, delete all articles marked as "Deleted" when closing a mailbox.

never

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 6.5.4 Expunging mailboxes.

ask

When closing mailboxes, nnimap will ask if you wish to expunge deleted articles or not.

nnimap-importantize-dormant

If non-nil (the default), marks dormant articles as ticked (as well), for other IMAP clients. Within Gnus, dormant articles will naturally still (only) be marked as dormant. This is to make dormant articles stand out, just like ticked articles, in other IMAP clients. (In other words, Gnus has two "Tick" marks and IMAP has only one.)

Probably the only reason for frobbing this would be if you're trying enable per-user persistent dormant flags, using something like:

(setcdr (assq 'dormant nnimap-mark-to-flag-alist) (format "gnus-dormant-%s" (user-login-name))) (setcdr (assq 'dormant nnimap-mark-to-predicate-alist) (format "KEYWORD gnus-dormant-%s" (user-login-name)))

In this case, you would not want the per-user dormant flag showing up as ticked for other users.

nnimap-expunge-search-string

This variable contain the IMAP search command sent to server when searching for articles eligible for expiring. The default is "UID %s NOT SINCE %s", where the first %s is replaced by UID set and the second %s is replaced by a date.

Probably the only useful value to change this to is "UID %s NOT SENTSINCE %s", which makes nnimap use the Date: in messages instead of the internal article date. See section 6.4.4 of RFC 2060 for more information on valid strings.

However, if nnimap-search-uids-not-since-is-evil is true, this variable has no effect since the search logic is reversed, as described below.

nnimap-authinfo-file

A file containing credentials used to log in on servers. The format is (almost) the same as the ftp `~/.netrc' file. See the variable nntp-authinfo-file for exact syntax; also see 6.2.1 NNTP. An example of an .authinfo line for an IMAP server, is:

machine students.uio.no login larsi password geheimnis port imap

Note that it should be port imap, or port 143, if you use a nnimap-stream of tls or ssl, even if the actual port number used is port 993 for secured IMAP. For convenience, Gnus will accept port imaps as a synonym of port imap.

nnimap-need-unselect-to-notice-new-mail

Unselect mailboxes before looking for new mail in them. Some servers seem to need this under some circumstances; it was reported that Courier 1.7.1 did.

nnimap-nov-is-evil

Never generate or use a local NOV database. Defaults to the value of gnus-agent.

Using a NOV database usually makes header fetching much faster, but it uses the UID SEARCH UID command, which is very slow on some servers (notably some versions of Courier). Since the Gnus Agent caches the information in the NOV database without using the slow command, this variable defaults to true if the Agent is in use, and false otherwise.

nnimap-search-uids-not-since-is-evil

Avoid the UID SEARCH UID message numbers NOT SINCE date command, which is slow on some IMAP servers (notably, some versions of Courier). Instead, use UID SEARCH SINCE date and prune the list of expirable articles within Gnus.

When Gnus expires your mail (see section 6.3.9 Expiring Mail), it starts with a list of expirable articles and asks the IMAP server questions like "Of these articles, which ones are older than a week?" While this seems like a perfectly reasonable question, some IMAP servers take a long time to answer it, since they seemingly go looking into every old article to see if it is one of the expirable ones. Curiously, the question "Of all articles, which ones are newer than a week?" seems to be much faster to answer, so setting this variable causes Gnus to ask this question and figure out the answer to the real question itself.

This problem can really sneak up on you: when you first configure Gnus, everything works fine, but once you accumulate a couple thousand messages, you start cursing Gnus for being so slow. On the other hand, if you get a lot of email within a week, setting this variable will cause a lot of network traffic between Gnus and the IMAP server.

nnimap-logout-timeout

There is a case where a connection to a IMAP server is unable to close, when connecting to the server via a certain kind of network, e.g. VPN. In that case, it will be observed that a connection between Emacs and the local network looks alive even if the server has closed a connection for some reason (typically, a timeout). Consequently, Emacs continues waiting for a response from the server for the LOGOUT command that Emacs sent, or hangs in other words. If you are in such a network, setting this variable to a number of seconds will be helpful. If it is set, a hung connection will be closed forcibly, after this number of seconds from the time Emacs sends the LOGOUT command. It should not be too small value but too large value will be inconvenient too. Perhaps the value 1.0 will be a good candidate but it might be worth trying some other values.

Example server specification:

(nnimap "mail.server.com" (nnimap-logout-timeout 1.0))