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 connec-
tion 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 lead-
ing 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 informa-
tion 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 imple-
mented)
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 " [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)