Provided by: tcllib_1.14-dfsg-1_all bug

NAME

       imap4 - imap client-side tcl implementation of imap protocol

SYNOPSIS

       package require Tcl  8.5

       package require imap4  ?0.3?

       ::imap4::open hostname ?port?

       ::imap4::login chan user pass

       ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?

       ::imap4::select chan ?mailbox?

       ::imap4::examine chan ?mailbox?

       ::imap4::fetch chan range ?-inline? ?attr ...?

       ::imap4::noop chan

       ::imap4::check chan

       ::imap4::folderinfo chan ?info?

       ::imap4::msginfo chan msgid ?info? ?defval?

       ::imap4::mboxinfo chan ?info?

       ::imap4::isableto chan ?capability?

       ::imap4::create chan mailbox

       ::imap4::delete chan mailbox

       ::imap4::rename chan oldname newname

       ::imap4::subscribe chan mailbox

       ::imap4::unsubscribe chan mailbox

       ::imap4::search chan expr ?...?

       ::imap4::close chan

       ::imap4::cleanup chan

       ::imap4::debugmode chan ?errormsg?

_________________________________________________________________

DESCRIPTION

       The imap4 library package provides the client side of the Internet Message Access Protocol
       (IMAP) using standard sockets or secure connection via  TLS/SSL.   The  package  is  fully
       implemented in Tcl.

       This document describes the procedures and explains their usage.

PROCEDURES

       This package defines the following public procedures:

       ::imap4::open hostname ?port?

              Open  a  new  IMAP  connection  and  initalize  the handler, the imap communication
              channel (handler) is returned.

              hostname - mail server

              port - connection port, defaults to 143

              The namespace variable ::imap4::use_ssl can  be  used  to  establish  to  a  secure
              connection  via  TSL/SSL  if  set  to  true.  In  this case default connection port
              defaults to 993.

              Note: For connecting via SSL the Tcl module tls must be already loaded otherwise an
              error is raised.

                  package require tls              ; # must be loaded for TLS/SSL
                  set ::imap4::use_ssl 1           ; # request a secure connection
                  set chan [::imap4::open $server] ; # default port is now 993

       ::imap4::login chan user pass

              Login using the IMAP LOGIN command, 0 is returned on successful login.

              chan - imap channel

              user - username

              pass - password

       ::imap4::folders chan ?-inline? ?mboxref? ?mboxname?

              Get list of matching folders, 0 is returned on success.

              Wildcards   '*'   as   '%'   are   allowed   for   mboxref  and  mboxname,  command
              ::imap4::folderinfo can be used to retrieve folder information.

              chan - imap channel

              mboxref - mailbox reference, defaults to ""

              mboxname - mailbox name, defaults to "*"

              If -inline is specified a compact folderlist is  returned  instead  of  the  result
              code.  All  flags  are  converted  to  lowercase and leading special characters are
              removed.

              {{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}

       ::imap4::select chan ?mailbox?

              Select a mailbox, 0 is returned on success.

              chan - imap channel

              mailbox - Path of the mailbox,  defaults to INBOX

              Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

       ::imap4::examine chan ?mailbox?

              "Examines" a mailbox, read-only equivalent of ::imap4::select.

              chan - imap channel

              mailbox - mailbox name or path to mailbox, defaults to INBOX

              Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

       ::imap4::fetch chan range ?-inline? ?attr ...?

              Fetch attributes from messages.

              The attributes are fetched and stored in the internal state which can be  retrieved
              with  command ::imap4::msginfo, 0 is returned on success.  If -inline is specified,
              alle records are returned as list in order as defined in the attr argument.

              chan - imap channel

              range - message index in format FROM:TO

              attr - imap attributes to fetch

              Note: If FROM is omitted, the 1st message is assumed, if TO is  ommitted  the  last
              message is assumed.  All message index ranges are 1-based.

       ::imap4::noop chan
              Send NOOP command to server. May get information as untagged data.

              chan - imap channel

       ::imap4::check chan
              Send CHECK command to server. Flush to disk.

              chan - imap channel

       ::imap4::folderinfo chan ?info?

              Get  information  on  the  recently  selected  folderlist.  If the info argument is
              omitted or a null string, the full list of information available for the mailbox is
              returned.

              If  the  required  information  name  is  suffixed  with a ? character, the command
              returns true if the information is available, or false if it is not.

              chan - imap channel

              info - folderlist options to retrieve

              Currently supported options: delim - hierarchy delimiter only, match - ref and mbox
              search  patterns (see ::imap4::folders), names - list of folder names only, flags -
              list of folder names with flags in format { {name {flags}} ... } (see also  compact
              format in function ::imap4::folders).

              {{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}

       ::imap4::msginfo chan msgid ?info? ?defval?

              Get  information (from previously collected using fetch) from a given msgid. If the
              'info' argument is omitted or a null string,  the  list  of  available  information
              options for the given message is returned.

              If  the  required  information  name  is  suffixed  with a ? character, the command
              returns true if the information is available, or false if it is not.

              chan - imap channel

              msgid - message number

              info - imap keyword to retrieve

              defval - default value, returned if info is empty

              Note: All message index ranges are 1-based.

       ::imap4::mboxinfo chan ?info?

              Get information on the currently selected mailbox.  If the info argument is omitted
              or  a  null  string,  the  list of available information options for the mailbox is
              returned.

              If the required information name is  suffixed  with  a  ?  character,  the  command
              returns true if the information is available, or false if it is not.

              chan - imap channel

              opt - mailbox option to retrieve

              Currently  supported  options:  EXISTS  (noof  msgs), RECENT (noof 'recent' flagged
              msgs), FLAGS

              In conjunction with OK: PERMFLAGS, UIDNEXT, UIDVAL, UNSEEN

              Div. states: CURRENT, FOUND, PERM.

                  ::imap4::select $chan INBOX
                  puts "[::imap4::mboxinfo $chan exists] mails in INBOX"

       ::imap4::isableto chan ?capability?

              Test for capability.   It  returns  1  if  requested  capability  is  supported,  0
              otherwise.  If capability is omitted all capability imap codes are retured as list.

              chan - imap channel

              info - imap keyword to retrieve

              Note: Use the capability command to ask the server if not already done by the user.

       ::imap4::create chan mailbox

              Create a new mailbox.

              chan - imap channel

              mailbox - mailbox name

       ::imap4::delete chan mailbox

              Delete a new mailbox.

              chan - imap channel

              mailbox - mailbox name

       ::imap4::rename chan oldname newname

              Rename a new mailbox.

              chan - imap channel

              mailbox - old mailbox name

              mailbox - new mailbox name

       ::imap4::subscribe chan mailbox

              Subscribe a new mailbox.

              chan - imap channel

              mailbox - mailbox name

       ::imap4::unsubscribe chan mailbox

              Unsubscribe a new mailbox.

              chan - imap channel

              mailbox - mailbox name

       ::imap4::search chan expr ?...?

              Search for mails matching search criterions, 0 is returned on success.

              chan - imap channel

              expr - imap search expression

              Notes: Currently the following search expressions are handled:

              Mail header flags: all mail header entries (ending with a colon ":"), like "From:",
              "Bcc:", ...

              Imap message search flags: ANSWERED, DELETED, DRAFT, FLAGGED,  RECENT,  SEEN,  NEW,
              OLD, UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNSEEN, ALL

              Imap header search flags: BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC

              Imap  conditional search flags: SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE,
              SINCE, BEFORE (not implemented), UID (not implemented)

              Logical search conditions: OR, NOT

              ::imap4::search $chan larger 4000 seen
              puts "Found messages: [::imap4::mboxinfo $chan found]"
              Found messages: 1 3 6 7 8 9 13 14 15 19 20

       ::imap4::close chan

              Close the mailbox. Permanently removes \Deleted messages and  return  to  the  AUTH
              state.

              chan - imap channel

       ::imap4::cleanup chan

              Destroy an IMAP connection and free the used space.  Close the mailbox. Permanently
              removes \Deleted messages and return to the AUTH state.

              chan - imap channel

       ::imap4::debugmode chan ?errormsg?
              Switch client into command line debug mode.

              This is a developers mode only that pass the control to the programmer. Every  line
              entered  is  sent  verbatim  to  the  server  (after  the  addition  of the request
              identifier).  The ::imap4::debug variable is automatically set to '1' on enter.

              It's possible to execute Tcl commands starting the line with a slash.

              chan - imap channel

              errormsg - optional error message to display

EXAMPLES

                  set user myusername
                  set pass xtremescrt
                  set server imap.test.tld
                  set FOLDER INBOX
                  # Connect to server
                  set imap [::imap4::open $server]
                  ::imap4::login $imap $user $pass
                  ::imap4::select $imap $FOLDER
                  # Output all the information about that mailbox
                  foreach info [::imap4::mboxinfo $imap] {
                      puts "$info -> [::imap4::mboxinfo $imap $info]"
                  }
                  # fetch 3 records inline
                  set fields {from: to: subject: size}
                  foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
                      puts -nonewline "#[incr idx])"
                      for {set j 0} {$j<[llength $fields]} {incr j} {
                          puts "\t[lindex $fields $j] [lindex $rec $j]"
                      }
                  }

                  # Show all the information available about the message ID 1
                  puts "Available info about message 1: [::imap4::msginfo $imap 1]"

                  # Use the capability stuff
                  puts "Capabilities: [::imap4::isableto $imap]"
                  puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"

                  # Cleanup
                  ::imap4::cleanup $imap

REFERENCES

       Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003,
       http://www.rfc-editor.org/rfc/rfc3501.txt

       OpenSSL, http://www.openssl.org/

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.  Only a small part of rfc3501 implemented.

       Please   report   such   in   the   category   imap4   of   the   Tcllib    SF    Trackers
       [http://sourceforge.net/tracker/?group_id=12883].    Please  also  report  any  ideas  for
       enhancements you may have for either package and/or documentation.

SEE ALSO

       ftp, http, imap, mime, pop3, tls

KEYWORDS

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