1pop3(n) Tcl POP3 Client Library pop3(n)
2______________________________________________________________________________
6
8 pop3 - Tcl client for POP3 email protocol
9
11 package require Tcl 8.4
12 package require pop3 ?1.9?
14 ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmd‐
16 prefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username
17 password ?port?
18 ::pop3::config chan
20 ::pop3::status chan
22 ::pop3::last chan
24 ::pop3::retrieve chan startIndex ?endIndex?
26 ::pop3::delete chan startIndex ?endIndex?
28 ::pop3::list chan ?msg?
30 ::pop3::top chan msg n
32 ::pop3::uidl chan ?msg?
34 ::pop3::capa chan
36 ::pop3::close chan
38______________________________________________________________________________
40
42 The pop3 package provides a simple Tcl-only client library for the POP3
43 email protocol as specified in RFC 1939 [http://www.rfc-edi‐
44 tor.org/rfc/rfc1939.txt]. It works by opening the standard POP3 socket
45 on the server, transmitting the username and password, then providing a
46 Tcl API to access the POP3 protocol commands. All server errors are
47 returned as Tcl errors (thrown) which must be caught with the Tcl catch
48 command.
49
51 This package uses the TLS package to handle the security for https urls
52 and other socket connections.
53 Policy decisions like the set of protocols to support and what ciphers
55 to use are not the responsibility of TLS, nor of this package itself
56 however. Such decisions are the responsibility of whichever applica‐
57 tion is using the package, and are likely influenced by the set of
58 servers the application will talk to as well.
59 For example, in light of the recent POODLE attack [http://googleonli‐
61 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
62 ssl-30.html] discovered by Google many servers will disable support for
63 the SSLv3 protocol. To handle this change the applications using TLS
64 must be patched, and not this package, nor TLS itself. Such a patch
65 may be as simple as generally activating tls1 support, as shown in the
66 example below.
67 package require tls
70 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
71 ... your own application code ...
73
76 ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmd‐
77 prefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username
78 password ?port?
79 Open a socket connection to the server specified by host, trans‐
80 mit the username and password as login information to the
81 server. The default port number is 110, which can be overridden
82 using the optional port argument. The return value is a channel
83 used by all of the other ::pop3 functions.
84 The command recognizes three options
86 -msex boolean
88 Setting this option tells the package that the server we
89 are talking to is an MS Exchange server (which has some
90 oddities we have to work around). The default is False.
91 -retr-mode retr|list|slow
93 The retrieval mode determines how exactly messages are
94 read from the server. The allowed values are retr, list
95 and slow. The default is retr. See ::pop3::retrieve for
96 more information.
97 -socketcmd cmdprefix
99 This option allows the user to overide the use of the
100 builtin socket command with any API-compatible command.
101 The envisioned main use is the securing of the new con‐
102 nection via SSL, through the specification of the command
103 tls::socket. This command is specially recognized as
104 well, changing the default port of the connection to 995.
105 -stls boolean
107 Setting this option tells the package to secure the con‐
108 nection using SSL or TLS. It performs STARTTLS as
109 described in IETF RFC 2595, it first opens a normal,
110 unencrypted connection and then negotiates a SSLv3 or
111 TLSv1 connection. If the connection cannot be secured,
112 the connection will be closed and an error will be
113 returned
114 -tls-callback stls-callback-command
116 This option allows the user to overide the tls::callback
117 used during the -stls SSL/TLS handshake. See the TLS man‐
118 ual for details on how to implement this callback.
119 ::pop3::config chan
121 Returns the configuration of the pop3 connection identified by
122 the channel handle chan as a serialized array.
123 ::pop3::status chan
125 Query the server for the status of the mail spool. The status
126 is returned as a list containing two elements, the first is the
127 number of email messages on the server and the second is the
128 size (in octets, 8 bit blocks) of the entire mail spool.
129 ::pop3::last chan
131 Query the server for the last email message read from the spool.
132 This value includes all messages read from all clients connect‐
133 ing to the login account. This command may not be supported by
134 the email server, in which case the server may return 0 or an
135 error.
136 ::pop3::retrieve chan startIndex ?endIndex?
138 Retrieve a range of messages from the server. If the endIndex
139 is not specified, only one message will be retrieved. The
140 return value is a list containing each message as a separate
141 element. See the startIndex and endIndex descriptions below.
142 The retrieval mode determines how exactly messages are read from
144 the server. The mode retr assumes that the RETR command delivers
145 the size of the message as part of the command status and uses
146 this to read the message efficiently. In mode list RETR does not
147 deliver the size, but the LIST command does and we use this to
148 retrieve the message size before the actual retrieval, which can
149 then be done efficiently. In the last mode, slow, the system is
150 unable to obtain the size of the message to retrieve in any man‐
151 ner and falls back to reading the message from the server line
152 by line.
153 It should also be noted that the system checks upon the config‐
155 ured mode and falls back to the slower modes if the above
156 assumptions are not true.
157 ::pop3::delete chan startIndex ?endIndex?
159 Delete a range of messages from the server. If the endIndex is
160 not specified, only one message will be deleted. Note, the
161 indices are not reordered on the server, so if you delete mes‐
162 sage 1, then the first message in the queue is message 2 (mes‐
163 sage index 1 is no longer valid). See the startIndex and endIn‐
164 dex descriptions below.
165 startIndex
167 The startIndex may be an index of a specific message
168 starting with the index 1, or it have any of the follow‐
169 ing values:
170 start This is a logical value for the first message in
172 the spool, equivalent to the value 1.
173 next The message immediately following the last message
175 read, see ::pop3::last.
176 end The most recent message in the spool (the end of
178 the spool). This is useful to retrieve only the
179 most recent message.
180 endIndex
182 The endIndex is an optional parameter and defaults to the
183 value "-1", which indicates to only retrieve the one mes‐
184 sage specified by startIndex. If specified, it may be an
185 index of a specific message starting with the index "1",
186 or it may have any of the following values:
187 last The message is the last message read by a POP3
189 client, see ::pop3::last.
190 end The most recent message in the spool (the end of
192 the spool).
193 ::pop3::list chan ?msg?
195 Returns the scan listing of the mailbox. If parameter msg is
196 given, then the listing only for that message is returned.
197 ::pop3::top chan msg n
199 Optional POP3 command, not all servers may support this.
200 ::pop3::top retrieves headers of a message, specified by parame‐
201 ter msg, and number of n lines from the message body.
202 ::pop3::uidl chan ?msg?
204 Optional POP3 command, not all servers may support this.
205 ::pop3::uidl returns the uid listing of the mailbox. If the
206 parameter msg is specified, then the listing only for that mes‐
207 sage is returned.
208 ::pop3::capa chan
210 Optional POP3 command, not all servers may support this.
211 ::pop3::capa returns a list of the capabilities of the server.
212 TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities.
213 See IETF RFC 2449.
214 ::pop3::close chan
216 Gracefully close the connect after sending a POP3 QUIT command
217 down the socket.
218
220 A pop3 connection can be secured with SSL/TLS by requiring the package
221 TLS and then using either the option -socketcmd or the option -stls of
222 the command pop3::open. The first method, option -socketcmd, will
223 force the use of the tls::socket command when opening the connection.
224 This is suitable for POP3 servers which expect SSL connections only.
225 These will generally be listening on port 995.
226 package require tls
229 tls::init -cafile /path/to/ca/cert -keyfile ...
230 # Create secured pop3 channel
232 pop3::open -socketcmd tls::socket \\
233 $thehost $theuser $thepassword
234 ...
236 The second method, option -stls, will connect to the standard POP3 port
238 and then perform an STARTTLS handshake. This will only work for POP3
239 servers which have this capability. The package will confirm that the
240 server supports STARTTLS and the handshake was performed correctly
241 before proceeding with authentication.
242 package require tls
245 tls::init -cafile /path/to/ca/cert -keyfile ...
246 # Create secured pop3 channel
248 pop3::open -stls 1 \\
249 $thehost $theuser $thepassword
250 ...
252
255 This document, and the package it describes, will undoubtedly contain
256 bugs and other problems. Please report such in the category pop3 of
257 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
258 also report any ideas for enhancements you may have for either package
259 and/or documentation.
260 When proposing code changes, please provide unified diffs, i.e the out‐
262 put of diff -u.
263 Note further that attachments are strongly preferred over inlined
265 patches. Attachments can be made by going to the Edit form of the
266 ticket immediately after its creation, and then using the left-most
267 button in the secondary navigation bar.
268
270 email, mail, pop, pop3, rfc 1939, secure, ssl, tls
271
273 Networking
274tcllib 1.9 pop3(n)