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? 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 provid-
       ing  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, 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.

       ::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  num-
	      ber 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 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 speci-
		     fied  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::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://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)