\section{Using POP3}\label{sec:pop3}
%
\begin{description}
\item[Used files:] pop3.scm pop3-obsolete.scm
\item[Name of the package:] pop3 pop3-obsolete.scm
\end{description}
%
\subsection{Overview}

The POP3 protocol allows access to email on a maildrop server. It is
often used in configurations where users connect from a client machine
which doesn't have a permanent network connection or isn't always
turned on, situations which make local SMTP delivery impossible. It is
the most common form of email access provided by Internet Service
Providers.

Two types of authentication are commonly used. The first, most basic
type involves sending a user's password in clear over the network, and
should be avoided. Unfortunately many POP3 clients only implement this
basic authentication. The digest authentication system involves the
server sending the client a ``challenge'' token; the client encodes
this token with the pass phrase and sends the coded information to the
server. This method avoids sending sensitive information over the
network.

Once connected, a client may request information about the number and
size of the messages waiting on the server, download selected messages
(either their headers or the entire content), and delete selected
messages.


\subsection{Entry points}

\begin{defundesc}{pop3-connect}{\ovar{host \ovar{logfile}}}{connection}
  Connect to the maildrop server named \semvar{host}. Optionally log
  the conversation with the server to \semvar{logfile}, which will be
  appended to if it exists, and created otherwise. The environment
  variable \ex{MAILHOST}, if set, will override the value of
  \semvar{host}.
\end{defundesc}

In the further descriptions of the procedures, \semvar{connection}
always refers to the result of \ex{pop3-\ob{}connect}.

\begin{defundesc}{pop3-login} {connection \ovar{login \ovar{password}}}{status}
  Log in to the mailhost. If a \semvar{login} and \semvar{password}
  are not provided, they are first searched for in the user's ~/.netrc
  file. USER/PASS authentication will be tried first, and if
  this fails, APOP authentication (secure) will be tried.
\end{defundesc}

\begin{defundesc}{pop3-login/APOP} {connection login password}{status}
  Log in to the mailhost using APOP authentication\footnote{The encryption
  (MD5) is currently done by an extern program that your system must
  provide. The expected name of the program is \ex{md5sum}. If your system
  uses another program for computing a MD5 message digest, change the
  program's name in \ex{md5-digest}.}.
\end{defundesc}

\begin{defundesc}{pop3-stat}{connection}{number bytes}
  Return the number of messages and the number of bytes waiting in the
  maildrop.
\end{defundesc}

\begin{defundesc}{pop3-get}{connection msgid}{status}
  Download message number \semvar{msgid} from the mailhost.
  \semvar{msgid} must be positive and less than the number of messages
  returned by the \ex{pop3-\ob{}stat} call. The message contents are sent to
  \ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
\end{defundesc}

\begin{defundesc}{pop3-headers}{connection msgid}{status}
  Download the headers of message number \semvar{msgid}. The data is sent to
  \ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
\end{defundesc}

\begin{defundesc}{pop3-last}{connection}{msgid}
  Return the highest accessed message-id number for the current
  session. This isn't in the RFC, but seems to be supported by several
  servers.
\end{defundesc}

\begin{defundesc}{pop3-delete}{connection msgid}{status}
  Mark message number \semvar{msgid} for deletion. The message will
  not be deleted until the client logs out.
\end{defundesc}

\begin{defundesc}{pop3-reset}{connection}{status}
  Any messages which have been marked for deletion are unmarked.
\end{defundesc}

\begin{defundesc}{pop3-quit}{connection}{status}
  Close the connection with the mailhost.
\end{defundesc}

\subsubsection*{Obsolete procedures}

Names in further versions of \ex{pop3} contained a colon (`\ex{:}')
after the prefix `\ex{pop3-}'. This is now changed to a hyphen
('\ex{-}'), accordingly to SUnet's philosophy. If you need the old
names, use the \ex{pop3\=obsolete}-package that maps the old names to
the new ones.

\subsection{Related work}

\begin{itemize}
\item Emacs is distributed with a C program called \ex{movemail} which
  can be compiled with support for the POP protocol. There is also an
  Emacs Lisp library called \ex{pop3.el} by Richard Pieri which
  includes APOP support.
\item Shriram Krishnamurth has written a POP3 library for MzScheme (as
  well as support for the NNTP protocol, for SMTP, \ldots).
\item Siod (a small-footprint Scheme implementation by George Carette)
  includes support for the POP3 protocol.
\item rfc1939 describes the POP3 protocol.
\end{itemize}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: