1imap4(n) imap client imap4(n)
2______________________________________________________________________________
6
8 imap4 - imap client-side tcl implementation of imap protocol
9
11 package require Tcl 8.5
12 package require imap4 ?0.5.2?
14 ::imap4::open hostname ?port?
16 ::imap4::starttls chan
18 ::imap4::login chan user pass
20 ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
22 ::imap4::select chan ?mailbox?
24 ::imap4::examine chan ?mailbox?
26 ::imap4::fetch chan range ?-inline? ?attr ...?
28 ::imap4::noop chan
30 ::imap4::check chan
32 ::imap4::folderinfo chan ?info?
34 ::imap4::msginfo chan msgid ?info? ?defval?
36 ::imap4::mboxinfo chan ?info?
38 ::imap4::isableto chan ?capability?
40 ::imap4::create chan mailbox
42 ::imap4::delete chan mailbox
44 ::imap4::rename chan oldname newname
46 ::imap4::subscribe chan mailbox
48 ::imap4::unsubscribe chan mailbox
50 ::imap4::search chan expr ?...?
52 ::imap4::close chan
54 ::imap4::cleanup chan
56 ::imap4::debugmode chan ?errormsg?
58 ::imap4::store chan range data flaglist
60 ::imap4::expunge chan
62 ::imap4::copy chan msgid mailbox
64 ::imap4::logout chan
66______________________________________________________________________________
68
70 The imap4 library package provides the client side of the Internet Mes‐
71 sage Access Protocol (IMAP) using standard sockets or secure connection
72 via TLS/SSL. The package is fully implemented in Tcl.
73 This document describes the procedures and explains their usage.
75
77 This package defines the following public procedures:
78 ::imap4::open hostname ?port?
80 Open a new IMAP connection and initalize the handler, the imap
82 communication channel (handler) is returned.
83 hostname - mail server
85 port - connection port, defaults to 143
87 The namespace variable ::imap4::use_ssl can be used to establish
89 to a secure connection via TSL/SSL if set to true. In this case
90 default connection port defaults to 993.
91 Note: For connecting via SSL the Tcl module tls must be already
93 loaded otherwise an error is raised.
94 package require tls ; # must be loaded for TLS/SSL
97 set ::imap4::use_ssl 1 ; # request a secure connection
98 set chan [::imap4::open $server] ; # default port is now 993
99 ::imap4::starttls chan
101 Use this when tasked with connecting to an unsecure port which
102 must be changed to a secure port prior to user login. This fea‐
103 ture is known as STARTTLS.
104 ::imap4::login chan user pass
106 Login using the IMAP LOGIN command, 0 is returned on successful
108 login.
109 chan - imap channel
111 user - username
113 pass - password
115 ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
117 Get list of matching folders, 0 is returned on success.
119 Wildcards '*' as '%' are allowed for mboxref and mboxname, com‐
121 mand ::imap4::folderinfo can be used to retrieve folder informa‐
122 tion.
123 chan - imap channel
125 mboxref - mailbox reference, defaults to ""
127 mboxname - mailbox name, defaults to "*"
129 If -inline is specified a compact folderlist is returned instead
131 of the result code. All flags are converted to lowercase and
132 leading special characters are removed.
133 {{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}
135 ::imap4::select chan ?mailbox?
137 Select a mailbox, 0 is returned on success.
139 chan - imap channel
141 mailbox - Path of the mailbox, defaults to INBOX
143 Prior to examine/select an open mailbox must be closed - see:
145 ::imap4::close.
146 ::imap4::examine chan ?mailbox?
148 "Examines" a mailbox, read-only equivalent of ::imap4::select.
150 chan - imap channel
152 mailbox - mailbox name or path to mailbox, defaults to INBOX
154 Prior to examine/select an open mailbox must be closed - see:
156 ::imap4::close.
157 ::imap4::fetch chan range ?-inline? ?attr ...?
159 Fetch attributes from messages.
161 The attributes are fetched and stored in the internal state
163 which can be retrieved with command ::imap4::msginfo, 0 is
164 returned on success. If -inline is specified, alle records are
165 returned as list in order as defined in the attr argument.
166 chan - imap channel
168 range - message index in format FROM:TO
170 attr - imap attributes to fetch
172 Note: If FROM is omitted, the 1st message is assumed, if TO is
174 ommitted the last message is assumed. All message index ranges
175 are 1-based.
176 ::imap4::noop chan
178 Send NOOP command to server. May get information as untagged
179 data.
180 chan - imap channel
182 ::imap4::check chan
184 Send CHECK command to server. Flush to disk.
185 chan - imap channel
187 ::imap4::folderinfo chan ?info?
189 Get information on the recently selected folderlist. If the
191 info argument is omitted or a null string, the full list of
192 information available for the mailbox is returned.
193 If the required information name is suffixed with a ? character,
195 the command returns true if the information is available, or
196 false if it is not.
197 chan - imap channel
199 info - folderlist options to retrieve
201 Currently supported options: delim - hierarchy delimiter only,
203 match - ref and mbox search patterns (see ::imap4::folders),
204 names - list of folder names only, flags - list of folder names
205 with flags in format { {name {flags}} ... } (see also compact
206 format in function ::imap4::folders).
207 {{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
210 ::imap4::msginfo chan msgid ?info? ?defval?
213 Get information (from previously collected using fetch) from a
215 given msgid. If the 'info' argument is omitted or a null string,
216 the list of available information options for the given message
217 is returned.
218 If the required information name is suffixed with a ? character,
220 the command returns true if the information is available, or
221 false if it is not.
222 chan - imap channel
224 msgid - message number
226 info - imap keyword to retrieve
228 defval - default value, returned if info is empty
230 Note: All message index ranges are 1-based.
232 ::imap4::mboxinfo chan ?info?
234 Get information on the currently selected mailbox. If the info
236 argument is omitted or a null string, the list of available
237 information options for the mailbox is returned.
238 If the required information name is suffixed with a ? character,
240 the command returns true if the information is available, or
241 false if it is not.
242 chan - imap channel
244 opt - mailbox option to retrieve
246 Currently supported options: EXISTS (noof msgs), RECENT (noof
248 'recent' flagged msgs), FLAGS
249 In conjunction with OK: PERMFLAGS, UIDNEXT, UIDVAL, UNSEEN
251 Div. states: CURRENT, FOUND, PERM.
253 ::imap4::select $chan INBOX
256 puts "[::imap4::mboxinfo $chan exists] mails in INBOX"
257 ::imap4::isableto chan ?capability?
259 Test for capability. It returns 1 if requested capability is
261 supported, 0 otherwise. If capability is omitted all capability
262 imap codes are retured as list.
263 chan - imap channel
265 info - imap keyword to retrieve
267 Note: Use the capability command to ask the server if not
269 already done by the user.
270 ::imap4::create chan mailbox
272 Create a new mailbox.
274 chan - imap channel
276 mailbox - mailbox name
278 ::imap4::delete chan mailbox
280 Delete a new mailbox.
282 chan - imap channel
284 mailbox - mailbox name
286 ::imap4::rename chan oldname newname
288 Rename a new mailbox.
290 chan - imap channel
292 mailbox - old mailbox name
294 mailbox - new mailbox name
296 ::imap4::subscribe chan mailbox
298 Subscribe a new mailbox.
300 chan - imap channel
302 mailbox - mailbox name
304 ::imap4::unsubscribe chan mailbox
306 Unsubscribe a new mailbox.
308 chan - imap channel
310 mailbox - mailbox name
312 ::imap4::search chan expr ?...?
314 Search for mails matching search criterions, 0 is returned on
316 success.
317 chan - imap channel
319 expr - imap search expression
321 Notes: Currently the following search expressions are handled:
323 Mail header flags: all mail header entries (ending with a colon
325 ":"), like "From:", "Bcc:", ...
326 Imap message search flags: ANSWERED, DELETED, DRAFT, FLAGGED,
328 RECENT, SEEN, NEW, OLD, UNANSWERED, UNDELETED, UNDRAFT,
329 UNFLAGGED, UNSEEN, ALL
330 Imap header search flags: BODY, CC, FROM, SUBJECT, TEXT, KEY‐
332 WORD, BCC
333 Imap conditional search flags: SMALLER, LARGER, ON, SENTBEFORE,
335 SENTON, SENTSINCE, SINCE, BEFORE (not implemented), UID (not
336 implemented)
337 Logical search conditions: OR, NOT
339 ::imap4::search $chan larger 4000 seen
341 puts "Found messages: [::imap4::mboxinfo $chan found]"
342 Found messages: 1 3 6 7 8 9 13 14 15 19 20
343 ::imap4::close chan
345 Close the mailbox. Permanently removes \Deleted messages and
347 return to the AUTH state.
348 chan - imap channel
350 ::imap4::cleanup chan
352 Destroy an IMAP connection and free the used space. Close the
354 mailbox. Permanently removes \Deleted messages and return to the
355 AUTH state.
356 chan - imap channel
358 ::imap4::debugmode chan ?errormsg?
360 Switch client into command line debug mode.
361 This is a developers mode only that pass the control to the pro‐
363 grammer. Every line entered is sent verbatim to the server
364 (after the addition of the request identifier). The
365 ::imap4::debug variable is automatically set to '1' on enter.
366 It's possible to execute Tcl commands starting the line with a
368 slash.
369 chan - imap channel
371 errormsg - optional error message to display
373 ::imap4::store chan range data flaglist
375 Alters data associated with a message in the selected mailbox.
377 chan - imap channel
379 range - message index in format FROM:TO
381 flaglist - Flags the data operates on.
383 data - The currently defined data items that can be stored are
385 shown below. Note that all of these data types may also be suf‐
386 fixed with ".SILENT" to suppress the untagged FETCH response.
387 FLAGS Replace the flags for the message (other than \Recent)
389 with the flaglist.
390 +FLAGS Add the flags in flaglist to the existing flags for the
392 message.
393 -FLAGS Remove the flags in flaglist to the existing flags for
395 the message.
396 For example:
398 ::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
401 ::imap4::expunge chan
404 Permanently removes all messages that have the \Deleted flag set
406 from the currently selected mailbox, without the need to close
407 the connection.
408 chan - imap channel
410 ::imap4::copy chan msgid mailbox
412 Copies the specified message (identified by its message number)
414 to the named mailbox, i.e. imap folder.
415 chan - imap channel
417 msgid - message number
419 mailbox - mailbox name
421 ::imap4::logout chan
423 Informs the server that the client is done with the connection
425 and closes the network connection. Permanently removes \Deleted
426 messages.
427 A new connection will need to be established to login once more.
429 chan - imap channel
431
433 set user myusername
434 set pass xtremescrt
435 set server imap.test.tld
436 set FOLDER INBOX
437 # Connect to server
438 set imap [::imap4::open $server]
439 ::imap4::login $imap $user $pass
440 ::imap4::select $imap $FOLDER
441 # Output all the information about that mailbox
442 foreach info [::imap4::mboxinfo $imap] {
443 puts "$info -> [::imap4::mboxinfo $imap $info]"
444 }
445 # fetch 3 records inline
446 set fields {from: to: subject: size}
447 foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
448 puts -nonewline "#[incr idx])"
449 for {set j 0} {$j<[llength $fields]} {incr j} {
450 puts "\t[lindex $fields $j] [lindex $rec $j]"
451 }
452 }
453 # Show all the information available about the message ID 1
455 puts "Available info about message 1: [::imap4::msginfo $imap 1]"
456 # Use the capability stuff
458 puts "Capabilities: [::imap4::isableto $imap]"
459 puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
460 # Cleanup
462 ::imap4::cleanup $imap
463
466 This package uses the TLS package to handle the security for https urls
467 and other socket connections.
468 Policy decisions like the set of protocols to support and what ciphers
470 to use are not the responsibility of TLS, nor of this package itself
471 however. Such decisions are the responsibility of whichever applica‐
472 tion is using the package, and are likely influenced by the set of
473 servers the application will talk to as well.
474 For example, in light of the recent POODLE attack [http://googleonli‐
476 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
477 ssl-30.html] discovered by Google many servers will disable support for
478 the SSLv3 protocol. To handle this change the applications using TLS
479 must be patched, and not this package, nor TLS itself. Such a patch
480 may be as simple as generally activating tls1 support, as shown in the
481 example below.
482 package require tls
485 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
486 ... your own application code ...
488
491 Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
492 RFC 3501, March 2003, http://www.rfc-editor.org/rfc/rfc3501.txt
493 OpenSSL, http://www.openssl.org/
495
497 This document, and the package it describes, will undoubtedly contain
498 bugs and other problems. Please report such in the category imap4 of
499 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
500 also report any ideas for enhancements you may have for either package
501 and/or documentation.
502 When proposing code changes, please provide unified diffs, i.e the out‐
504 put of diff -u.
505 Note further that attachments are strongly preferred over inlined
507 patches. Attachments can be made by going to the Edit form of the
508 ticket immediately after its creation, and then using the left-most
509 button in the secondary navigation bar. Only a small part of rfc3501
510 implemented.
511
513 ftp, http, imap, mime, pop3, tls
514
516 email, imap, internet, mail, net, rfc3501, ssl, tls
517tcllib 0.5.3 imap4(n)