Provided by: tcllib_1.14-dfsg-1_all bug

NAME

       pop3 - Tcl client for POP3 email protocol

SYNOPSIS

       package require Tcl  8.2

       package require pop3  ?1.7?

       ::pop3::open  ?-msex  0|1?  ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? ?-stls 0|1?
       ?-tls-callback stls-callback-command? host username password ?port?

       ::pop3::config chan

       ::pop3::status chan

       ::pop3::last chan

       ::pop3::retrieve chan startIndex ?endIndex?

       ::pop3::delete chan startIndex ?endIndex?

       ::pop3::list chan ?msg?

       ::pop3::top chan msg n

       ::pop3::uidl chan ?msg?

       ::pop3::capa chan

       ::pop3::close chan

_________________________________________________________________

DESCRIPTION

       The pop3 package provides a simple Tcl-only client library for the POP3 email protocol  as
       specified  in  RFC  1939 [http://www.rfc-editor.org/rfc/rfc1939.txt].  It works by opening
       the standard POP3 socket on the server,  transmitting  the  username  and  password,  then
       providing  a Tcl API to access the POP3 protocol commands.  All server errors are returned
       as Tcl errors (thrown) which must be caught with the Tcl catch command.

API

       ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd  cmdprefix?  ?-stls  0|1?
       ?-tls-callback stls-callback-command? host username password ?port?
              Open a socket connection to the server specified by host, transmit the username and
              password as login information to the server.  The default port number is 110, which
              can  be overridden using the optional port argument.  The return value is a channel
              used by all of the other ::pop3 functions.

              The command recognizes three options

              -msex boolean
                     Setting this option tells the package that the server we are talking  to  is
                     an  MS Exchange server (which has some oddities we have to work around). The
                     default is False.

              -retr-mode retr|list|slow
                     The retrieval mode determines how exactly messages are read from the server.
                     The  allowed  values  are  retr,  list  and  slow.  The default is retr. See
                     ::pop3::retrieve for more information.

              -socketcmd cmdprefix
                     This option allows the user to overide the use of the builtin socket command
                     with  any API-compatible command. The envisioned main use is the securing of
                     the new connection  via  SSL,  through  the  specification  of  the  command
                     tls::socket.  This  command  is  specially  recognized as well, changing the
                     default port of the connection to 995.

              -stls boolean
                     Setting this option tells the package to secure the connection using SSL  or
                     TLS.  It  performs  STARTTLS as described in IETF RFC 2595, it first opens a
                     normal,  unencrypted  connection  and  then  negotiates  a  SSLv3  or  TLSv1
                     connection.  If  the  connection  cannot  be secured, the connection will be
                     closed and an error will be returned

              -tls-callback stls-callback-command
                     This option allows the user to overide the  tls::callback  used  during  the
                     -stls  SSL/TLS handshake. See the TLS manual for details on how to implement
                     this callback.

       ::pop3::config chan
              Returns the configuration of the pop3 connection identified by the  channel  handle
              chan as a serialized array.

       ::pop3::status chan
              Query  the  server  for  the status of the mail spool.  The status is returned as a
              list containing two elements, the first is the number  of  email  messages  on  the
              server  and  the  second  is  the size (in octets, 8 bit blocks) of the entire mail
              spool.

       ::pop3::last chan
              Query the server for the last email  message  read  from  the  spool.   This  value
              includes  all messages read from all clients connecting to the login account.  This
              command may not be supported by the email server, in  which  case  the  server  may
              return 0 or an error.

       ::pop3::retrieve chan startIndex ?endIndex?
              Retrieve  a  range  of messages from the server.  If the endIndex is not specified,
              only one message will be retrieved.  The return value is  a  list  containing  each
              message as a separate element.  See the startIndex and endIndex descriptions below.

              The  retrieval  mode  determines how exactly messages are read from the server. The
              mode retr assumes that the RETR command delivers the size of the message as part of
              the command status and uses this to read the message efficiently. In mode list RETR
              does not deliver the size, but the LIST command does and we use  this  to  retrieve
              the  message  size before the actual retrieval, which can then be done efficiently.
              In the last mode, slow, the system is unable to obtain the size of the  message  to
              retrieve  in  any manner and falls back to reading the message from the server line
              by line.

              It should also be noted that the system checks upon the configured mode  and  falls
              back to the slower modes if the above assumptions are not true.

       ::pop3::delete chan startIndex ?endIndex?
              Delete a range of messages from the server.  If the endIndex is not specified, only
              one message will be deleted.  Note, the indices are not reordered on the server, so
              if  you delete message 1, then the first message in the queue is message 2 (message
              index 1 is no longer valid).  See the startIndex and endIndex descriptions below.

              startIndex
                     The startIndex may be an index of a specific message starting with the index
                     1, or it have any of the following values:

                     start  This  is  a  logical  value  for  the  first  message  in  the spool,
                            equivalent to the value 1.

                     next   The  message  immediately  following  the  last  message  read,   see
                            ::pop3::last.

                     end    The most recent message in the spool (the end of the spool).  This is
                            useful to retrieve only the most recent message.

              endIndex
                     The endIndex is an optional parameter and defaults to the value "-1",  which
                     indicates  to  only  retrieve  the  one message specified by startIndex.  If
                     specified, it may be an index of a specific message starting with the  index
                     "1", or it may have any of the following values:

                     last   The  message  is  the  last  message  read  by  a  POP3  client,  see
                            ::pop3::last.

                     end    The most recent message in the spool (the end of the spool).

       ::pop3::list chan ?msg?
              Returns the scan listing of the mailbox.  If  parameter  msg  is  given,  then  the
              listing only for that message is returned.

       ::pop3::top chan msg n
              Optional  POP3  command,  not  all servers may support this.  ::pop3::top retrieves
              headers of a message, specified by parameter msg, and number of n  lines  from  the
              message body.

       ::pop3::uidl chan ?msg?
              Optional  POP3 command, not all servers may support this.  ::pop3::uidl returns the
              uid listing of the mailbox. If the parameter msg is  specified,  then  the  listing
              only for that message is returned.

       ::pop3::capa chan
              Optional  POP3  command,  not all servers may support this.  ::pop3::capa returns a
              list of the capabilities of the server.  TOP, SASL, UIDL, LOGIN-DELAY and STLS  are
              typical capabilities.  See IETF RFC 2449.

       ::pop3::close chan
              Gracefully close the connect after sending a POP3 QUIT command down the socket.

SECURE MAIL TRANSFER

       A  pop3 connection can be secured with SSL/TLS by requiring the package TLS and then using
       either the option -socketcmd or the option -stls of the  command  pop3::open.   The  first
       method,  option -socketcmd, will force the use of the tls::socket command when opening the
       connection. This is suitable for POP3 servers which expect  SSL  connections  only.  These
       will generally be listening on port 995.

                package require tls
                tls::init -cafile /path/to/ca/cert -keyfile ...

                # Create secured pop3 channel
                pop3::open -socketcmd tls::socket \\
                   $thehost $theuser $thepassword

                ...

       The  second  method, option -stls, will connect to the standard POP3 port and then perform
       an STARTTLS handshake. This will only work for POP3 servers which  have  this  capability.
       The package will confirm that the server supports STARTTLS and the handshake was performed
       correctly before proceeding with authentication.

                package require tls
                tls::init -cafile /path/to/ca/cert -keyfile ...

                # Create secured pop3 channel
                pop3::open -stls 1 \\
                   $thehost $theuser $thepassword

                ...

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report  such  in  the  category  pop3  of  the  Tcllib  SF  Trackers
       [http://sourceforge.net/tracker/?group_id=12883].   Please  also  report  any  ideas   for
       enhancements you may have for either package and/or documentation.

KEYWORDS

       email, mail, pop, pop3, rfc 1939, secure, ssl, tls

CATEGORY

       Networking