


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 cmd-
       prefix? 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::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-edi-
       tor.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? host username password ?port?
              Open a socket connection to the server specified by host, trans-
              mit  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





pop3                           1.7                              1





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


              -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 con-
                     nection 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.

       ::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 byte 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  connect-
              ing  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 man-
              ner and falls back to reading the message from the  server  line
              by line.

              It  should  also  be  noted  that  the  system  checks  upon the



pop3                           1.7                              2





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


              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 mes-
              sage 1, then the first message in the queue is message  2  (mes-
              sage index 1 is no longer valid).  See the startIndex and endIn-
              dex descriptions below.

              startIndex
                     The startIndex may be an  index  of  a  specific  message
                     starting  with the index 1, or it have any of the follow-
                     ing 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 mes-
                             sage 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 mes-
                     sage 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 parame-
              ter 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 mes-
              sage is returned.




pop3                           1.7                              3





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


       ::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 the option -socketcmd of the command  pop3::open  to
       force the use of the tls::socket command when opening the connection.

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

            # Create secured pop3 channel
            pop3::open -socketcmd tls::socket \\
                 $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://source-
       forge.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                              4


