1pop3(n) Tcl POP3 Client Library pop3(n)
2______________________________________________________________________________
6
8 pop3 - Tcl client for POP3 email protocol
9
11 package require Tcl 8.2
12 package require pop3 ?1.6.3?
14 ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? host username
16 password ?port?
17 ::pop3::config chan
19 ::pop3::status chan
21 ::pop3::last chan
23 ::pop3::retrieve chan startIndex ?endIndex?
25 ::pop3::delete chan startIndex ?endIndex?
27 ::pop3::list chan ?msg?
29 ::pop3::top chan msg n
31 ::pop3::uidl chan ?msg?
33 ::pop3::close chan
35_________________________________________________________________
37
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
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 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 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 ::pop3::config chan
66 Returns the configuration of the pop3 connection identified by
67 the channel handle chan as a serialized array.
68 ::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 ::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 ::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 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 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 ::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 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 start This is a logical value for the first message in
117 the spool, equivalent to the value 1.
118 next The message immediately following the last message
120 read, see ::pop3::last.
121 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 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 last The message is the last message read by a POP3
134 client, see ::pop3::last.
135 end The most recent message in the spool (the end of
137 the spool).
138 ::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 ::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 ::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 ::pop3::close chan
155 Gracefully close the connect after sending a POP3 QUIT command
156 down the socket.
157
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
166 email, mail, pop, pop3, rfc 1939
167pop3 1.6.3 pop3(n)