1pop3(n)                     Tcl POP3 Client Library                    pop3(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       pop3 - Tcl client for POP3 email protocol
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require pop3  ?1.9?
14
15       ::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
19       ::pop3::config chan
20
21       ::pop3::status chan
22
23       ::pop3::last chan
24
25       ::pop3::retrieve chan startIndex ?endIndex?
26
27       ::pop3::delete chan startIndex ?endIndex?
28
29       ::pop3::list chan ?msg?
30
31       ::pop3::top chan msg n
32
33       ::pop3::uidl chan ?msg?
34
35       ::pop3::capa chan
36
37       ::pop3::close chan
38
39______________________________________________________________________________
40

DESCRIPTION

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

TLS SECURITY CONSIDERATIONS

51       This package uses the TLS package to handle the security for https urls
52       and other socket connections.
53
54       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
60       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
68
69                  package require tls
70                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
71
72                  ... your own application code ...
73
74

API

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
85              The command recognizes three options
86
87              -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
92              -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
98              -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
106              -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
115              -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
120       ::pop3::config chan
121              Returns the configuration of the pop3 connection  identified  by
122              the channel handle chan as a serialized array.
123
124       ::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
130       ::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
137       ::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
143              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
154              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
158       ::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
166              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
171                     start  This  is  a logical value for the first message in
172                            the spool, equivalent to the value 1.
173
174                     next   The message immediately following the last message
175                            read, see ::pop3::last.
176
177                     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
181              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
188                     last   The  message  is  the  last message read by a POP3
189                            client, see ::pop3::last.
190
191                     end    The most recent message in the spool (the  end  of
192                            the spool).
193
194       ::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
198       ::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
203       ::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
209       ::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
215       ::pop3::close chan
216              Gracefully close the connect after sending a POP3  QUIT  command
217              down the socket.
218

SECURE MAIL TRANSFER

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
227
228                package require tls
229                tls::init -cafile /path/to/ca/cert -keyfile ...
230
231                # Create secured pop3 channel
232                pop3::open -socketcmd tls::socket \\
233                   $thehost $theuser $thepassword
234
235                ...
236
237       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
243
244                package require tls
245                tls::init -cafile /path/to/ca/cert -keyfile ...
246
247                # Create secured pop3 channel
248                pop3::open -stls 1 \\
249                   $thehost $theuser $thepassword
250
251                ...
252
253

BUGS, IDEAS, FEEDBACK

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
261       When proposing code changes, please provide unified diffs, i.e the out‐
262       put of diff -u.
263
264       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

KEYWORDS

270       email, mail, pop, pop3, rfc 1939, secure, ssl, tls
271

CATEGORY

273       Networking
274
275
276
277tcllib                                1.9                              pop3(n)
Impressum