Provided by: tcllib_1.17-dfsg-1_all 
NAME
pop3 - Tcl client for POP3 email protocol
SYNOPSIS
package require Tcl 8.4
package require pop3 ?1.9?
::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.
TLS SECURITY CONSIDERATIONS
This package uses the TLS package to handle the security for https urls and other socket
connections.
Policy decisions like the set of protocols to support and what ciphers to use are not the
responsibility of TLS, nor of this package itself however. Such decisions are the
responsibility of whichever application is using the package, and are likely influenced by
the set of servers the application will talk to as well.
For example, in light of the recent POODLE attack
[http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
ssl-30.html] discovered by Google many servers will disable support for the SSLv3
protocol. To handle this change the applications using TLS must be patched, and not this
package, nor TLS itself. Such a patch may be as simple as generally activating tls1
support, as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
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 Trackers
[http://core.tcl.tk/tcllib/reportlist]. 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