imap4(n)                          imap client                         imap4(n)



______________________________________________________________________________

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



imap4                                 0.3                             imap4(n)
