GNU Info

(gnus)Mail Source Specifiers

---

Next: Mail Source Customization Up: Mail Sources

---

Enter node , (file) or (file)node

Mail Source Specifiers
......................

   You tell Gnus how to fetch mail by setting `mail-sources' (Note:
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 path of the file.  Defaults to the value of the `MAIL'
          environment variable or `/usr/mail/spool/user-name'.

     An example file mail source:

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

     Or using the default path:

          (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.  Setting `nnmail-scan-directory-mail-source-once' to
     non-nil force Gnus to scan the mail source only once.

     Keywords:

    `:path'
          The path 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 110') 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.

    `: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 path 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.  Note: 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 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
          `kerberos4', `ssl' 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 `kerberos4', `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 `nil'.  Then all articles in the mailbox
          is fetched, no matter what.  For a complete list of
          predicates, see RFC 2060 §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 §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 www.hotmail.com,
     webmail.netscape.com, www.netaddress.com, www.my-deja.com.

     NOTE: Now mail.yahoo.com provides POP3 service, so POP mail source
     is suggested.

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

     WARNING: Mails may 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.

Function Interface
..................

   Some of the above keywords specify a Lisp function to be executed.
For each keyword `:foo', the Lisp variable `foo' is bound to the value
of the keyword while the function is executing.  For example, consider
the following mail-source setting:

     (setq mail-sources '((pop :user "jrl"
                               :server "pophost" :function fetchfunc)))

   While the function `fetchfunc' is executing, the symbol `user' is
bound to `"jrl"', and the symbol `server' is bound to `"pophost"'.  The
symbols `port', `password', `program', `prescript', `postscript',
`function', and `authentication' are also bound (to their default
values).

   See above for a list of keywords for each type of mail source.