1pop3(n) Tcl POP3 Client Library pop3(n)
2______________________________________________________________________________
6
8 pop3 - Tcl client for POP3 email protocol
9
11 package require Tcl 8.5
12 package require pop3 ?1.10?
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 de‐
109 scribed in IETF RFC 2595, it first opens a normal, unen‐
110 crypted connection and then negotiates a SSLv3 or TLSv1
111 connection. If the connection cannot be secured, the con‐
112 nection will be closed and an error will be returned
113 -tls-callback stls-callback-command
115 This option allows the user to overide the tls::callback
116 used during the -stls SSL/TLS handshake. See the TLS man‐
117 ual for details on how to implement this callback.
118 ::pop3::config chan
120 Returns the configuration of the pop3 connection identified by
121 the channel handle chan as a serialized array.
122 ::pop3::status chan
124 Query the server for the status of the mail spool. The status
125 is returned as a list containing two elements, the first is the
126 number of email messages on the server and the second is the
127 size (in octets, 8 bit blocks) of the entire mail spool.
128 ::pop3::last chan
130 Query the server for the last email message read from the spool.
131 This value includes all messages read from all clients connect‐
132 ing to the login account. This command may not be supported by
133 the email server, in which case the server may return 0 or an
134 error.
135 ::pop3::retrieve chan startIndex ?endIndex?
137 Retrieve a range of messages from the server. If the endIndex
138 is not specified, only one message will be retrieved. The re‐
139 turn value is a list containing each message as a separate ele‐
140 ment. See the startIndex and endIndex descriptions below.
141 The retrieval mode determines how exactly messages are read from
143 the server. The mode retr assumes that the RETR command delivers
144 the size of the message as part of the command status and uses
145 this to read the message efficiently. In mode list RETR does not
146 deliver the size, but the LIST command does and we use this to
147 retrieve the message size before the actual retrieval, which can
148 then be done efficiently. In the last mode, slow, the system is
149 unable to obtain the size of the message to retrieve in any man‐
150 ner and falls back to reading the message from the server line
151 by line.
152 It should also be noted that the system checks upon the config‐
154 ured mode and falls back to the slower modes if the above as‐
155 sumptions are not true.
156 ::pop3::delete chan startIndex ?endIndex?
158 Delete a range of messages from the server. If the endIndex is
159 not specified, only one message will be deleted. Note, the in‐
160 dices are not reordered on the server, so if you delete message
161 1, then the first message in the queue is message 2 (message in‐
162 dex 1 is no longer valid). See the startIndex and endIndex de‐
163 scriptions below.
164 startIndex
166 The startIndex may be an index of a specific message
167 starting with the index 1, or it have any of the follow‐
168 ing values:
169 start This is a logical value for the first message in
171 the spool, equivalent to the value 1.
172 next The message immediately following the last message
174 read, see ::pop3::last.
175 end The most recent message in the spool (the end of
177 the spool). This is useful to retrieve only the
178 most recent message.
179 endIndex
181 The endIndex is an optional parameter and defaults to the
182 value "-1", which indicates to only retrieve the one mes‐
183 sage specified by startIndex. If specified, it may be an
184 index of a specific message starting with the index "1",
185 or it may have any of the following values:
186 last The message is the last message read by a POP3
188 client, see ::pop3::last.
189 end The most recent message in the spool (the end of
191 the spool).
192 ::pop3::list chan ?msg?
194 Returns the scan listing of the mailbox. If parameter msg is
195 given, then the listing only for that message is returned.
196 ::pop3::top chan msg n
198 Optional POP3 command, not all servers may support this.
199 ::pop3::top retrieves headers of a message, specified by parame‐
200 ter msg, and number of n lines from the message body.
201 ::pop3::uidl chan ?msg?
203 Optional POP3 command, not all servers may support this.
204 ::pop3::uidl returns the uid listing of the mailbox. If the pa‐
205 rameter msg is specified, then the listing only for that message
206 is returned.
207 ::pop3::capa chan
209 Optional POP3 command, not all servers may support this.
210 ::pop3::capa returns a list of the capabilities of the server.
211 TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities.
212 See IETF RFC 2449.
213 ::pop3::close chan
215 Gracefully close the connect after sending a POP3 QUIT command
216 down the socket.
217
219 A pop3 connection can be secured with SSL/TLS by requiring the package
220 TLS and then using either the option -socketcmd or the option -stls of
221 the command pop3::open. The first method, option -socketcmd, will
222 force the use of the tls::socket command when opening the connection.
223 This is suitable for POP3 servers which expect SSL connections only.
224 These will generally be listening on port 995.
225 package require tls
228 tls::init -cafile /path/to/ca/cert -keyfile ...
229 # Create secured pop3 channel
231 pop3::open -socketcmd tls::socket \
232 $thehost $theuser $thepassword
233 ...
235 The second method, option -stls, will connect to the standard POP3 port
237 and then perform an STARTTLS handshake. This will only work for POP3
238 servers which have this capability. The package will confirm that the
239 server supports STARTTLS and the handshake was performed correctly be‐
240 fore proceeding with authentication.
241 package require tls
244 tls::init -cafile /path/to/ca/cert -keyfile ...
245 # Create secured pop3 channel
247 pop3::open -stls 1 \
248 $thehost $theuser $thepassword
249 ...
251
254 This document, and the package it describes, will undoubtedly contain
255 bugs and other problems. Please report such in the category pop3 of
256 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
257 also report any ideas for enhancements you may have for either package
258 and/or documentation.
259 When proposing code changes, please provide unified diffs, i.e the out‐
261 put of diff -u.
262 Note further that attachments are strongly preferred over inlined
264 patches. Attachments can be made by going to the Edit form of the
265 ticket immediately after its creation, and then using the left-most
266 button in the secondary navigation bar.
267
269 email, mail, pop, pop3, rfc 1939, secure, ssl, tls
270
272 Networking
273tcllib 1.10 pop3(n)