--- name: "pop3" section: "3tcl" platform: "linux" package: "tcllib" version: "2.0+dfsg-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/pop3" --- # pop3(3tcl) Tcl client for POP3 email protocol ``` ``` ## NAME pop3 - Tcl client for POP3 email protocol ## SYNOPSIS package require **Tcl 8.5 9** package require **pop3 ?1.11?** **::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. When proposing code changes, please provide *unified diffs*, i.e the output of **diff -u**. Note further that *attachments* are strongly preferred over inlined patches. Attachments can be made by going to the **Edit** form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. ## KEYWORDS email, mail, pop, pop3, rfc 1939, secure, ssl, tls ## CATEGORY Networking