pop3(n)                     Tcl POP3 Client Library                    pop3(n)



______________________________________________________________________________

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



pop3                                  1.7                              pop3(n)
