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.2
12
13       package require pop3  ?1.6.3?
14
15       ::pop3::open  ?-msex  0|1?  ?-retr-mode  retr|list|slow?  host username
16       password ?port?
17
18       ::pop3::config chan
19
20       ::pop3::status chan
21
22       ::pop3::last chan
23
24       ::pop3::retrieve chan startIndex ?endIndex?
25
26       ::pop3::delete chan startIndex ?endIndex?
27
28       ::pop3::list chan ?msg?
29
30       ::pop3::top chan msg n
31
32       ::pop3::uidl chan ?msg?
33
34       ::pop3::close chan
35
36_________________________________________________________________
37

DESCRIPTION

39       The pop3 package provides a simple Tcl-only client library for the POP3
40       email   protocol   as   specified   in  RFC  1939  (http://www.rfc-edi
41       tor.org/rfc/rfc1939.txt). It works by opening the standard POP3  socket
42       on the server, transmitting the username and password, then providing a
43       Tcl API to access the POP3 protocol commands.  All  server  errors  are
44       returned as Tcl errors (thrown) which must be caught with the Tcl catch
45       command.
46

COMMANDS

48       ::pop3::open ?-msex  0|1?  ?-retr-mode  retr|list|slow?  host  username
49       password ?port?
50              Open a socket connection to the server specified by host, trans‐
51              mit the username  and  password  as  login  information  to  the
52              server.  The default port number is 110, which can be overridden
53              using the optional port argument.  The return value is a channel
54              used by all of the other ::pop3 functions.
55
56              The  command  recognizes  the  options -msex and -retr-mode. The
57              first of them can be used to notify the package of the fact that
58              the  server  to talk to is an MS Exchange server (which has some
59              oddities we have to work around). The default is 0.
60
61              The retrieval mode determines how exactly messages are read from
62              the  server.  The  allowed  values  are retr, list and slow. The
63              default is retr. See ::pop3::retrieve for more information.
64
65       ::pop3::config chan
66              Returns the configuration of the pop3 connection  identified  by
67              the channel handle chan as a serialized array.
68
69       ::pop3::status chan
70              Query  the  server for the status of the mail spool.  The status
71              is returned as a list containing two elements, the first is  the
72              number  of  email  messages  on the server and the second is the
73              size (in octets, 8 byte blocks) of the entire mail spool.
74
75       ::pop3::last chan
76              Query the server for the last email message read from the spool.
77              This  value includes all messages read from all clients connect‐
78              ing to the login account.  This command may not be supported  by
79              the  email  server,  in which case the server may return 0 or an
80              error.
81
82       ::pop3::retrieve chan startIndex ?endIndex?
83              Retrieve a range of messages from the server.  If  the  endIndex
84              is  not  specified,  only  one  message  will be retrieved.  The
85              return value is a list containing each  message  as  a  separate
86              element.  See the startIndex and endIndex descriptions below.
87
88              The retrieval mode determines how exactly messages are read from
89              the server. The mode retr assumes that the RETR command delivers
90              the  size  of the message as part of the command status and uses
91              this to read the message efficiently. In mode list RETR does not
92              deliver  the  size, but the LIST command does and we use this to
93              retrieve the message size before the actual retrieval, which can
94              then  be done efficiently. In the last mode, slow, the system is
95              unable to obtain the size of the message to retrieve in any man‐
96              ner  and  falls back to reading the message from the server line
97              by line.
98
99              It should also be noted that the system checks upon the  config‐
100              ured  mode  and  falls  back  to  the  slower modes if the above
101              assumptions are not true.
102
103       ::pop3::delete chan startIndex ?endIndex?
104              Delete a range of messages from the server.  If the endIndex  is
105              not  specified,  only  one  message  will be deleted.  Note, the
106              indices are not reordered on the server, so if you  delete  mes‐
107              sage  1,  then the first message in the queue is message 2 (mes‐
108              sage index 1 is no longer valid).  See the startIndex and endIn‐
109              dex descriptions below.
110
111              startIndex
112                     The  startIndex  may  be  an  index of a specific message
113                     starting with the index 1, or it have any of the  follow‐
114                     ing values:
115
116                     start  This  is  a logical value for the first message in
117                            the spool, equivalent to the value 1.
118
119                     next   The message immediately following the last message
120                            read, see ::pop3::last.
121
122                     end    The  most  recent message in the spool (the end of
123                            the spool).  This is useful to retrieve  only  the
124                            most recent message.
125
126              endIndex
127                     The endIndex is an optional parameter and defaults to the
128                     value "-1", which indicates to only retrieve the one mes‐
129                     sage specified by startIndex.  If specified, it may be an
130                     index of a specific message starting with the index  "1",
131                     or it may have any of the following values:
132
133                     last   The  message  is  the  last message read by a POP3
134                            client, see ::pop3::last.
135
136                     end    The most recent message in the spool (the  end  of
137                            the spool).
138
139       ::pop3::list chan ?msg?
140              Returns  the  scan  listing  of the mailbox. If parameter msg is
141              given, then the listing only for that message is returned.
142
143       ::pop3::top chan msg n
144              Optional  POP3  command,  not  all  servers  may  support  this.
145              ::pop3::top retrieves headers of a message, specified by parame‐
146              ter msg, and number of n lines from the message body.
147
148       ::pop3::uidl chan ?msg?
149              Optional  POP3  command,  not  all  servers  may  support  this.
150              ::pop3::uidl  returns  the  uid  listing  of the mailbox. If the
151              parameter msg is specified, then the listing only for that  mes‐
152              sage is returned.
153
154       ::pop3::close chan
155              Gracefully  close  the connect after sending a POP3 QUIT command
156              down the socket.
157

BUGS, IDEAS, FEEDBACK

159       This document, and the package it describes, will  undoubtedly  contain
160       bugs  and  other  problems.  Please report such in the category pop3 of
161       the         Tcllib         SF         Trackers          [http://source
162       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
163       enhancements you may have for either package and/or documentation.
164

KEYWORDS

166       email, mail, pop, pop3, rfc 1939
167
168
169
170pop3                                 1.6.3                             pop3(n)
Impressum