imap4(n) imap client imap4(n) 







imap4 - imap client-side tcl implementation of imap protocol








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?












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.








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

  












    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









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/








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.








ftp, http, imap, mime, pop3, tls








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







  

    0.3
    imap4