gnus: Mail Source Specifiers
6.4.4.1 Mail Source Specifiers
..............................
You tell Gnus how to fetch mail by setting ‘mail-sources’ (
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 ‘mail-sources’ is global for all mail groups. You can specify an
additional mail source for a particular group by including the ‘group’
mail specifier in ‘mail-sources’, and setting a ‘mail-source’ group
parameter (Group Parameters) specifying a single mail source.
When this is used, ‘mail-sources’ is typically just ‘(group)’; the
‘mail-source’ parameter for a group might look like this:
(mail-source . (file :path "home/user/spools/foo.spool"))
This means that the group’s (and only this group’s) messages will be
fetched from the spool file ‘/user/spools/foo.spool’.
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 the ‘movemail’ and temporary file 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, 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
(e.g., ‘:port 1234’) or a string (e.g., ‘: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.
One popular way to use this is to set up an SSH tunnel to
access the POP server. Here’s an example:
(pop :server "127.0.0.1"
:port 1234
:user "foo"
:password "secret"
:prescript
"nohup ssh -f -L 1234:pop.server:110 remote.host sleep 3600 &")
‘: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’.
‘:leave’
Non-‘nil’ if the mail is to be left on the POP server after
fetching. Only the built-in ‘pop3-movemail’ program (the
default) supports this keyword.
If this is a number, leave mails on the server for this many
days since you first checked new mails. In that case, mails
once fetched will never be fetched again by the UIDL control.
If this is ‘nil’ (the default), mails will be deleted on the
server right after fetching. If this is neither ‘nil’ nor a
number, all mails will be left on the server, and you will end
up getting the same mails again and again.
The ‘pop3-uidl-file’ variable specifies the file to which the
UIDL data are locally stored. The default value is
‘~/.pop3-uidl’.
Note that POP servers maintain no state information between
sessions, so what the client believes is there and what is
actually there may not match up. If they do not, then you may
get duplicate mails or the whole thing can fall apart and
leave you with a corrupt mailbox.
If the ‘:program’ and ‘:function’ keywords aren’t specified,
‘pop3-movemail’ will be used.
Here are some examples for getting mail from a POP server.
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")
Leave mails on the server for 14 days:
(pop :server "my.pop.server"
:user "user-name" :password "secret"
:leave 14)
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 (i.e., 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. Using
IMAP, for more information.
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
Make sure nothing is interfering with the output of the
program, e.g., don’t forget to redirect the error output to
the void. 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 receives incoming
mail. Instead of a single mailbox, this can be a list of
mailboxes to fetch mail from.
‘: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")
‘group’
Get the actual mail source from the ‘mail-source’ group parameter,
Group Parameters.
“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.
Info Catalog
gnus: Mail Sources
gnus: Mail Source Functions