1imap4(n)                          imap client                         imap4(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       imap4 - imap client-side tcl implementation of imap protocol
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require imap4  ?0.5.3?
14
15       ::imap4::open hostname ?port?
16
17       ::imap4::starttls chan
18
19       ::imap4::login chan user pass
20
21       ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
22
23       ::imap4::select chan ?mailbox?
24
25       ::imap4::examine chan ?mailbox?
26
27       ::imap4::fetch chan range ?-inline? ?attr ...?
28
29       ::imap4::noop chan
30
31       ::imap4::check chan
32
33       ::imap4::folderinfo chan ?info?
34
35       ::imap4::msginfo chan msgid ?info? ?defval?
36
37       ::imap4::mboxinfo chan ?info?
38
39       ::imap4::isableto chan ?capability?
40
41       ::imap4::create chan mailbox
42
43       ::imap4::delete chan mailbox
44
45       ::imap4::rename chan oldname newname
46
47       ::imap4::subscribe chan mailbox
48
49       ::imap4::unsubscribe chan mailbox
50
51       ::imap4::search chan expr ?...?
52
53       ::imap4::close chan
54
55       ::imap4::cleanup chan
56
57       ::imap4::debugmode chan ?errormsg?
58
59       ::imap4::store chan range data flaglist
60
61       ::imap4::expunge chan
62
63       ::imap4::copy chan msgid mailbox
64
65       ::imap4::logout chan
66
67______________________________________________________________________________
68

DESCRIPTION

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
74       This document describes the procedures and explains their usage.
75

PROCEDURES

77       This package defines the following public procedures:
78
79       ::imap4::open hostname ?port?
80
81              Open  a  new IMAP connection and initalize the handler, the imap
82              communication channel (handler) is returned.
83
84              hostname - mail server
85
86              port - connection port, defaults to 143
87
88              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
92              Note: For connecting via SSL the Tcl module tls must be  already
93              loaded otherwise an error is raised.
94
95
96                  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
100       ::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
105       ::imap4::login chan user pass
106
107              Login  using the IMAP LOGIN command, 0 is returned on successful
108              login.
109
110              chan - imap channel
111
112              user - username
113
114              pass - password
115
116       ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
117
118              Get list of matching folders, 0 is returned on success.
119
120              Wildcards '*' as '%' are allowed for mboxref and mboxname,  com‐
121              mand ::imap4::folderinfo can be used to retrieve folder informa‐
122              tion.
123
124              chan - imap channel
125
126              mboxref - mailbox reference, defaults to ""
127
128              mboxname - mailbox name, defaults to "*"
129
130              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
134              {{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}
135
136       ::imap4::select chan ?mailbox?
137
138              Select a mailbox, 0 is returned on success.
139
140              chan - imap channel
141
142              mailbox - Path of the mailbox,  defaults to INBOX
143
144              Prior to examine/select an open mailbox must be  closed  -  see:
145              ::imap4::close.
146
147       ::imap4::examine chan ?mailbox?
148
149              "Examines" a mailbox, read-only equivalent of ::imap4::select.
150
151              chan - imap channel
152
153              mailbox - mailbox name or path to mailbox, defaults to INBOX
154
155              Prior  to  examine/select  an open mailbox must be closed - see:
156              ::imap4::close.
157
158       ::imap4::fetch chan range ?-inline? ?attr ...?
159
160              Fetch attributes from messages.
161
162              The attributes are fetched and  stored  in  the  internal  state
163              which  can  be retrieved with command ::imap4::msginfo, 0 is re‐
164              turned on success.  If -inline is specified,  alle  records  are
165              returned as list in order as defined in the attr argument.
166
167              chan - imap channel
168
169              range - message index in format FROM:TO
170
171              attr - imap attributes to fetch
172
173              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
177       ::imap4::noop chan
178              Send  NOOP  command  to  server. May get information as untagged
179              data.
180
181              chan - imap channel
182
183       ::imap4::check chan
184              Send CHECK command to server. Flush to disk.
185
186              chan - imap channel
187
188       ::imap4::folderinfo chan ?info?
189
190              Get information on the recently  selected  folderlist.   If  the
191              info  argument is omitted or a null string, the full list of in‐
192              formation available for the mailbox is returned.
193
194              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
198              chan - imap channel
199
200              info - folderlist options to retrieve
201
202              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
208
209              {{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
210
211
212       ::imap4::msginfo chan msgid ?info? ?defval?
213
214              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
219              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
223              chan - imap channel
224
225              msgid - message number
226
227              info - imap keyword to retrieve
228
229              defval - default value, returned if info is empty
230
231              Note: All message index ranges are 1-based.
232
233       ::imap4::mboxinfo chan ?info?
234
235              Get  information on the currently selected mailbox.  If the info
236              argument is omitted or a null string, the list of available  in‐
237              formation options for the mailbox is returned.
238
239              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
243              chan - imap channel
244
245              opt - mailbox option to retrieve
246
247              Currently  supported  options:  EXISTS (noof msgs), RECENT (noof
248              'recent' flagged msgs), FLAGS
249
250              In conjunction with OK: PERMFLAGS, UIDNEXT, UIDVAL, UNSEEN
251
252              Div. states: CURRENT, FOUND, PERM.
253
254
255                  ::imap4::select $chan INBOX
256                  puts "[::imap4::mboxinfo $chan exists] mails in INBOX"
257
258       ::imap4::isableto chan ?capability?
259
260              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
264              chan - imap channel
265
266              info - imap keyword to retrieve
267
268              Note: Use the capability command to ask the server  if  not  al‐
269              ready done by the user.
270
271       ::imap4::create chan mailbox
272
273              Create a new mailbox.
274
275              chan - imap channel
276
277              mailbox - mailbox name
278
279       ::imap4::delete chan mailbox
280
281              Delete a new mailbox.
282
283              chan - imap channel
284
285              mailbox - mailbox name
286
287       ::imap4::rename chan oldname newname
288
289              Rename a new mailbox.
290
291              chan - imap channel
292
293              mailbox - old mailbox name
294
295              mailbox - new mailbox name
296
297       ::imap4::subscribe chan mailbox
298
299              Subscribe a new mailbox.
300
301              chan - imap channel
302
303              mailbox - mailbox name
304
305       ::imap4::unsubscribe chan mailbox
306
307              Unsubscribe a new mailbox.
308
309              chan - imap channel
310
311              mailbox - mailbox name
312
313       ::imap4::search chan expr ?...?
314
315              Search  for  mails  matching search criterions, 0 is returned on
316              success.
317
318              chan - imap channel
319
320              expr - imap search expression
321
322              Notes: Currently the following search expressions are handled:
323
324              Mail header flags: all mail header entries (ending with a  colon
325              ":"), like "From:", "Bcc:", ...
326
327              Imap  message  search  flags: ANSWERED, DELETED, DRAFT, FLAGGED,
328              RECENT, SEEN, NEW,  OLD,  UNANSWERED,  UNDELETED,  UNDRAFT,  UN‐
329              FLAGGED, UNSEEN, ALL
330
331              Imap  header  search  flags: BODY, CC, FROM, SUBJECT, TEXT, KEY‐
332              WORD, BCC
333
334              Imap conditional search flags: SMALLER, LARGER, ON,  SENTBEFORE,
335              SENTON, SENTSINCE, SINCE, BEFORE (not implemented), UID (not im‐
336              plemented)
337
338              Logical search conditions: OR, NOT
339
340              ::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
344       ::imap4::close chan
345
346              Close the mailbox. Permanently removes \Deleted messages and re‐
347              turn to the AUTH state.
348
349              chan - imap channel
350
351       ::imap4::cleanup chan
352
353              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
357              chan - imap channel
358
359       ::imap4::debugmode chan ?errormsg?
360              Switch client into command line debug mode.
361
362              This is a developers mode only that pass the control to the pro‐
363              grammer. Every line entered is sent verbatim to the server  (af‐
364              ter the addition of the request identifier).  The ::imap4::debug
365              variable is automatically set to '1' on enter.
366
367              It's possible to execute Tcl commands starting the line  with  a
368              slash.
369
370              chan - imap channel
371
372              errormsg - optional error message to display
373
374       ::imap4::store chan range data flaglist
375
376              Alters data associated with a message in the selected mailbox.
377
378              chan - imap channel
379
380              range - message index in format FROM:TO
381
382              flaglist - Flags the data operates on.
383
384              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
388              FLAGS  Replace  the  flags  for the message (other than \Recent)
389                     with the flaglist.
390
391              +FLAGS Add the flags in flaglist to the existing flags  for  the
392                     message.
393
394              -FLAGS Remove  the  flags  in flaglist to the existing flags for
395                     the message.
396
397              For example:
398
399
400                ::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
401
402
403       ::imap4::expunge chan
404
405              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
409              chan - imap channel
410
411       ::imap4::copy chan msgid mailbox
412
413              Copies the specified message (identified by its message  number)
414              to the named mailbox, i.e. imap folder.
415
416              chan - imap channel
417
418              msgid - message number
419
420              mailbox - mailbox name
421
422       ::imap4::logout chan
423
424              Informs  the  server that the client is done with the connection
425              and closes the network connection. Permanently removes  \Deleted
426              messages.
427
428              A new connection will need to be established to login once more.
429
430              chan - imap channel
431

EXAMPLES

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
454                  # Show all the information available about the message ID 1
455                  puts "Available info about message 1: [::imap4::msginfo $imap 1]"
456
457                  # Use the capability stuff
458                  puts "Capabilities: [::imap4::isableto $imap]"
459                  puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
460
461                  # Cleanup
462                  ::imap4::cleanup $imap
463
464

TLS SECURITY CONSIDERATIONS

466       This package uses the TLS package to handle the security for https urls
467       and other socket connections.
468
469       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
475       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
483
484                  package require tls
485                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
486
487                  ... your own application code ...
488
489

REFERENCES

491       Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL  -  VERSION  4rev1",
492       RFC 3501, March 2003, http://www.rfc-editor.org/rfc/rfc3501.txt
493
494       OpenSSL, http://www.openssl.org/
495

BUGS, IDEAS, FEEDBACK

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
503       When proposing code changes, please provide unified diffs, i.e the out‐
504       put of diff -u.
505
506       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

SEE ALSO

513       ftp, http, imap, mime, pop3, tls
514

KEYWORDS

516       email, imap, internet, mail, net, rfc3501, ssl, tls
517

CATEGORY

519       Networking
520
521
522
523tcllib                               0.5.3                            imap4(n)
Impressum