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