6.3.4.1 Mail Source Specifiers

You tell Gnus how to fetch mail by setting mail-sources (see section 6.3.4.4 Fetching Mail) to a mail source specifier.

Here's an example:

(pop :server "pop3.mailserver.com" :user "myname")

As can be observed, a mail source specifier is a list where the first element is a mail source type, followed by an arbitrary number of keywords. Keywords that are not explicitly specified are given default values.

The following mail source types are available:

file

Get mail from a single file; typically from the mail spool.

Keywords:

:path

The file name. Defaults to the value of the MAIL environment variable or the value of rmail-spool-directory (usually something like `/usr/mail/spool/user-name').

:prescript

:postscript

Script run before/after fetching mail.

An example file mail source:

(file :path "/usr/spool/mail/user-name")

Or using the default file name:

(file)

If the mail spool file is not located on the local machine, it's best to use POP or IMAP or the like to fetch the mail. You can not use ange-ftp file names here--it has no way to lock the mail spool while moving the mail.

If it's impossible to set up a proper server, you can use ssh instead.

(setq mail-sources '((file :prescript "ssh host bin/getmail >%t")))

The `getmail' script would look something like the following:

#!/bin/sh # getmail - move mail from spool to stdout # flu@iki.fi MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail TMP=$HOME/Mail/tmp rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP

Alter this script to fit find the `movemail' you want to use.

directory

Get mail from several files in a directory. This is typically used when you have procmail split the incoming mail into several files. That is, there is a one-to-one correspondence between files in that directory and groups, so that mail from the file `foo.bar.spool' will be put in the group foo.bar. (You can change the suffix to be used instead of .spool.) Setting nnmail-scan-directory-mail-source-once to non-nil forces Gnus to scan the mail source only once. This is particularly useful if you want to scan mail groups at a specified level.

There is also the variable nnmail-resplit-incoming, if you set that to a non-nil value, then the normal splitting process is applied to all the files from the directory, 6.3.3 Splitting Mail.

Keywords:

:path

The name of the directory where the files are. There is no default value.

:suffix

Only files ending with this suffix are used. The default is `.spool'.

:predicate

Only files that have this predicate return non-nil are returned. The default is identity. This is used as an additional filter--only files that have the right suffix and satisfy this predicate are considered.

:prescript

:postscript

Script run before/after fetching mail.

An example directory mail source:

(directory :path "/home/user-name/procmail-dir/" :suffix ".prcml")

pop

Get mail from a POP server.

Keywords:

:server

The name of the POP server. The default is taken from the MAILHOST environment variable.

:port

The port number of the POP server. This can be a number (eg, `:port 1234') or a string (eg, `:port "pop3"'). If it is a string, it should be a service name as listed in `/etc/services' on Unix systems. The default is `"pop3"'. On some systems you might need to specify it as `"pop-3"' instead.

:user

The user name to give to the POP server. The default is the login name.

:password

The password to give to the POP server. If not specified, the user is prompted.

:program

The program to use to fetch mail from the POP server. This should be a format-like string. Here's an example:

fetchmail %u@%s -P %p %t

The valid format specifier characters are:

`t'

The name of the file the mail is to be moved to. This must always be included in this string.

`s'

The name of the server.

`P'

The port number of the server.

`u'

The user name to use.

`p'

The password to use.

The values used for these specs are taken from the values you give the corresponding keywords.

:prescript

A script to be run before fetching the mail. The syntax is the same as the :program keyword. This can also be a function to be run.

:postscript

A script to be run after fetching the mail. The syntax is the same as the :program keyword. This can also be a function to be run.

:function

The function to use to fetch mail from the POP server. The function is called with one parameter--the name of the file where the mail should be moved to.

:authentication

This can be either the symbol password or the symbol apop and says what authentication scheme to use. The default is password.

If the :program and :function keywords aren't specified, pop3-movemail will be used.

Here are some examples. Fetch from the default POP server, using the default user name, and default fetcher:

(pop)

Fetch from a named server with a named user and password:

(pop :server "my.pop.server" :user "user-name" :password "secret")

Use `movemail' to move the mail:

(pop :program "movemail po:%u %t %p")

maildir

Get mail from a maildir. This is a type of mailbox that is supported by at least qmail and postfix, where each file in a special directory contains exactly one mail.

Keywords:

:path

The name of the directory where the mails are stored. The default is taken from the MAILDIR environment variable or `~/Maildir/'.

:subdirs

The subdirectories of the Maildir. The default is `("new" "cur")'.

You can also get mails from remote hosts (because maildirs don't suffer from locking problems).

Two example maildir mail sources:

(maildir :path "/home/user-name/Maildir/" :subdirs ("cur" "new"))

(maildir :path "/user@remotehost.org:~/Maildir/" :subdirs ("new"))

imap

Get mail from a IMAP server. If you don't want to use IMAP as intended, as a network mail reading protocol (ie with nnimap), for some reason or other, Gnus let you treat it similar to a POP server and fetches articles from a given IMAP mailbox. See section 6.5 IMAP, for more information.

Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support you may need external programs and libraries, See section 6.5 IMAP.

Keywords:

:server

The name of the IMAP server. The default is taken from the MAILHOST environment variable.

:port

The port number of the IMAP server. The default is `143', or `993' for TLS/SSL connections.

:user

The user name to give to the IMAP server. The default is the login name.

:password

The password to give to the IMAP server. If not specified, the user is prompted.

:stream

What stream to use for connecting to the server, this is one of the symbols in imap-stream-alist. Right now, this means `gssapi', `kerberos4', `starttls', `tls', `ssl', `shell' or the default `network'.

:authentication

Which authenticator to use for authenticating to the server, this is one of the symbols in imap-authenticator-alist. Right now, this means `gssapi', `kerberos4', `digest-md5', `cram-md5', `anonymous' or the default `login'.

:program

When using the `shell' :stream, the contents of this variable is mapped into the imap-shell-program variable. This should be a format-like string (or list of strings). Here's an example:

ssh %s imapd

The valid format specifier characters are:

`s'

The name of the server.

`l'

User name from imap-default-user.

`p'

The port number of the server.

The values used for these specs are taken from the values you give the corresponding keywords.

:mailbox

The name of the mailbox to get mail from. The default is `INBOX' which normally is the mailbox which receive incoming mail.

:predicate

The predicate used to find articles to fetch. The default, `UNSEEN UNDELETED', is probably the best choice for most people, but if you sometimes peek in your mailbox with a IMAP client and mark some articles as read (or; SEEN) you might want to set this to `1:*'. Then all articles in the mailbox is fetched, no matter what. For a complete list of predicates, see RFC 2060 section 6.4.4.

:fetchflag

How to flag fetched articles on the server, the default `\Deleted' will mark them as deleted, an alternative would be `\Seen' which would simply mark them as read. These are the two most likely choices, but more flags are defined in RFC 2060 section 2.3.2.

:dontexpunge

If non-nil, don't remove all articles marked as deleted in the mailbox after finishing the fetch.

An example IMAP mail source:

(imap :server "mail.mycorp.com" :stream kerberos4 :fetchflag "\\Seen")

webmail

Get mail from a webmail server, such as http://www.hotmail.com/, http://webmail.netscape.com/, http://www.netaddress.com/, http://mail.yahoo.com/.

NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is required for url "4.0pre.46".

WARNING: Mails may be lost. NO WARRANTY.

Keywords:

:subtype

The type of the webmail server. The default is hotmail. The alternatives are netscape, netaddress, my-deja.

:user

The user name to give to the webmail server. The default is the login name.

:password

The password to give to the webmail server. If not specified, the user is prompted.

:dontexpunge

If non-nil, only fetch unread articles and don't move them to trash folder after finishing the fetch.

An example webmail source:

(webmail :subtype 'hotmail :user "user-name" :password "secret")

Common Keywords

Common keywords can be used in any type of mail source.

Keywords:

:plugged

If non-nil, fetch the mail even when Gnus is unplugged. If you use directory source to get mail, you can specify it as in this example:

(setq mail-sources '((directory :path "/home/pavel/.Spool/" :suffix "" :plugged t)))

Gnus will then fetch your mail even when you are unplugged. This is useful when you use local mail and news.