This manual page is for Mac OS X version 10.6.3

Reading manual pages

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.6.3?

       ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? 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-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.

COMMANDS
       ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? 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 the options -msex and -retr-mode. The first of  them  can  be  used  to
              notify  the package of the fact that the server to talk to is an MS Exchange server (which has
              some oddities we have to work around). The default is 0.

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

       ::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  contain-ing containing
              ing  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 mes-sages messages
              sages  read  from  all  clients connecting to the login account.  This command may not be sup-ported supported
              ported 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 mes-sage message
              sage will be retrieved.  The return value is a list containing each message as a separate ele-ment. element.
              ment.  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 mes-sage message
              sage 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 fol-lowing following
                     lowing 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::close chan
              Gracefully close the connect after sending a POP3 QUIT command down the socket.


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



pop3                                                1.6.3                                            pop3(n)