imap4 (n) - Linux Manuals

imap4: imap client-side tcl implementation of imap protocol

Command to display imap4 manual in Linux: $ man n imap4

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

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.

KEYWORDS

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

imap4 (n) - Linux Manuals

imap4: imap client-side tcl implementation of imap protocol

NAME

SYNOPSIS

DESCRIPTION

PROCEDURES

EXAMPLES

REFERENCES

BUGS, IDEAS, FEEDBACK

KEYWORDS

SEE ALSO

Pages related to imap4