This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Mail/Folder/Emaul, Next: Mail/Folder/FastReader, Prev: Mail/Folder, Up: Module List An Emaul folder interface for Mail::Folder. ******************************************* NAME ==== Mail::Folder::Emaul - An Emaul folder interface for Mail::Folder. *WARNING: This code is in alpha release. Expect the interface to change.* SYNOPSIS ======== `use Mail::Folder::Emaul;' DESCRIPTION =========== This module provides an interface to the *emaul* folder mechanism. It is currently intended to be used as an example of hooking a folder interface into Mail::Folder. The folder structure of *Emaul* is styled after *mh*. It uses directories for folders and numerically-named files for the individual mail messages. The current message for a particular folder is stored in a file `.current_msg' in the folder directory. Folder locking is accomplished through the use of a .lock file in the folder directory. If a Timeout option is specified when the object is created, that value will be used to determine the timeout for attempting to aquire a folder lock. The default is 10 seconds. METHODS ======= open($folder_name) ------------------ Populates the `Mail::Folder' object with information about the folder. * Call the superclass open method. * Make sure it is a valid mbox folder. * Check to see it it is readonly * Lock the folder if it is not readonly. (This is dubious) * For every message file in the `$folder_name' directory, add the message_number to the list of messages in the object. * Load the contents of `$folder_dir/.current_msg' into `$self->{Current}'. * Set current_message. * Load message labels. * Unlock the folder if it is not readonly. sync ---- Flushes any pending changes out to the original folder. * Call the superclass sync method. * Return `-1' if the folder is readonly. * Return `-1' if the folder cannot be locked. * Scan the folder directory for message files that were not present the last time the folder was either opened or synced and absorb them. * For every pending delete, unlink that file in the folder directory * Clear out the 'pending delete' list. * Update the `.current_msg' file and the `.msg_labels' file if the `NotMUA' option is not set. * Return the number of new messages found. pack ---- Calls the superclass pack method. Return 0 if the folder is readonly. Return 0 if the folder cannot be locked. Renames the message files in the folder so that there are no gaps in the numbering sequence. It will tweak current_message accordingly. Old deleted message files (ones that start with `,') are also renamed as necessary. It will abandon the operation and return 0 if a rename fails, otherwise it returns 1. Please note that pack acts on the real folder. get_message($msg_number) ------------------------ Calls the superclass get_message method. Retrieves the given mail message file into a Mail::Internet object reference and returns the reference. It will coerce the `From_' field into a `Mail-From' field, add the 'seen' label to the message, remove the `Content-Length' field if present, and cache the header. Returns undef on failure. get_message_file($msg_number) ----------------------------- Calls the superclass get_message_file method. Retrieves the given mail message file and returns the name of the file. Returns undef on failure. get_header($msg_number) ----------------------- Calls the superclass get_header method. If the particular header has never been retrieved then get_header loads the header of the given mail message into a member of `$self->{Messages}{$msg_number}' and returns the object reference If the header for the given mail message has already been retrieved in a prior call to get_header, then the cached entry is returned. The `Content-Length' field is deleted from the header object it returns. append_message($mref) --------------------- Calls the superclass `append_message' method. Returns 0 if it cannot lock the folder. Appends the contents of the mail message contained `$mref' to the the folder. It also caches the header. Please note that, contrary to other documentation for *Mail::Folder*, the Emaul `append_message' method actually updates the real folder, rather than queueing it up for a subsequent sync. The dup and `refile' methods are also affected. This will be fixed soon. update_message($msg_number, $mref) ---------------------------------- Calls the superclass `update_message' method. It returns 0 if it cannot lock the folder. Replaces the message pointed to by `$msg_number' with the contents of the Mail::Internet object reference `$mref'. Please note that, contrary to other documentation for *Mail::Folder*, the Emaul `update_message' method actually updates the real folder, rather than queueing it up for a subsequent sync. This will be fixed soon. is_valid_folder_format($foldername) ----------------------------------- Returns 0 if the folder is not a directory or looks like a maildir folder. The current logic allows it to handle MH directories, but watch out; you should probably set the `NotMUA' option so the interface doesn't create it's own little folder droppings like `.msg_labels' and such. create($foldername) ------------------- Returns 0 if the folder already exists. Creates a new folder named `$foldername' with mode `0700' and then returns 1. AUTHOR ====== Kevin Johnson <`kjj@pobox.com'> COPYRIGHT ========= Copyright (c) 1996-1998 Kevin Johnson . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Folder/FastReader, Next: Mail/Folder/Maildir, Prev: Mail/Folder/Emaul, Up: Module List A fast mailbox reader ********************* NAME ==== Mail::Folder::FastReader - A fast mailbox reader SYNOPSIS ======== use Mail::Folder::FastReader qw( read_email reset_file ); open MAILBOX,"saved-mail"; reset_file(MAILBOX); while (1) { my ($status, $email, $line_number) = read_email(); last unless $status print < SEE ALSO ======== grepmail, mail(1), printmail(1), Mail::Internet(3) Crocker, D. H., Standard for the Format of Arpa Internet Text Messages, RFC822.  File: pm.info, Node: Mail/Folder/Maildir, Next: Mail/Folder/Mbox, Prev: Mail/Folder/FastReader, Up: Module List A maildir folder interface for Mail::Folder. ******************************************** NAME ==== Mail::Folder::Maildir - A maildir folder interface for Mail::Folder. *WARNING: This code is in alpha release. Expect the interface to change.* SYNOPSIS ======== `use Mail::Folder::Maildir;' DESCRIPTION =========== This module provides an interface to the *maildir* folder mechanism. The *maildir* folder format is the preferred folder mechanism for the *qmail* mail transport agent. It uses directories as folders and files as messages. It also provides separate directories for new and current messages. One of the most distinguishing features of the `maildir' format is that it accomplishes it's job without the need for file locking, so it's better equipped to deal with things like nfs mounts and the like. More information about qmail is available from `http://pobox.com/~djb/qmail.html'. METHODS ======= open($folder_name) ------------------ Populates the `Mail::Folder' object with information about the folder. * Call the superclass open method. * Make sure it is a valid maildir folder. * Detect whether the folder is readonly. * Clean the folder `tmp' directory. * Move message in folder new directory into the `cur' directory. * Clean up the folder `tmp' directory. * Moves message file in new directory to the `cur' directory. * For every message in the folder, add a new message number to the list of messages in the object, and remember the association between the message number and the message filename. * Set current_message to 1 (ugh). close ----- Deletes the working copy of the folder and calls the superclass close method. sync ---- * Call the superclass sync method. * Scan for new messages and absorb them. * If the folder is not readonly, expunge messages marked for deletion. * Update the `:info' portion of each file in the folder. * Return the quantity of new messages found. pack ---- Calls the superclass pack method. Reassociates the filenames in the folders to message numbers, deleting holes in the sequence of message numbers. get_message($msg_number) ------------------------ Call the superclass get_message method. Retrieves the contents of the file pointed to by `$msg_number' into a Mail::Internet object reference, caches the header, marks the message as 'seen' and returns the reference. get_message_file($msg_number) ----------------------------- Call the superclass get_message_file method. Retrieves the given mail message file pointed to by $msg_number and returns the name of the file. get_header($msg_number) ----------------------- If the particular header has never been retrieved then get_header loads the header of the given mail message into a member of `$self->{Messages}{$msg_number}' and returns the object reference If the header for the given mail message has already been retrieved in a prior call to get_header, then the cached entry is returned. append_message($mref) --------------------- Calls the superclass `append_message' method. Writes a temporary copy of the message in `$mref' to the folder `tmp' directory, then moves that temporary copy into the folder `cur' directory. It will delete the `From_' line in the header if one is present. update_message($msg_number, $mref) ---------------------------------- Calls the superclass `update_message' method. Writes a temporary copy of the message in `$mref' to the folder `tmp' directory, then moves that temporary copy into the folder `cur' directory, replacing the message pointed to by `$msg_number'. It will delete the `From_' line in the header if one is present. is_valid_folder_format($foldername) ----------------------------------- Returns 1 if the folder is a directory and contains `tmp', `cur', and new subdirectories otherwise returns 0. create($foldername) ------------------- Creates a new folder named `$foldername'. Returns 0 if the folder already exists, otherwise returns 1. AUTHOR ====== Kevin Johnson <`kjj@pobox.com'> COPYRIGHT ========= Copyright (c) 1996-1998 Kevin Johnson . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Folder/Mbox, Next: Mail/Folder/NNTP, Prev: Mail/Folder/Maildir, Up: Module List A Unix mbox interface for Mail::Folder. *************************************** NAME ==== Mail::Folder::Mbox - A Unix mbox interface for Mail::Folder. *WARNING: This code is in alpha release. Expect the interface to change.* SYNOPSIS ======== `use Mail::Folder::Mbox;' DESCRIPTION =========== This module provides an interface to unix mbox folders. The mbox folder format is the standard monolithic folder structure prevalent on Unix. A single folder is contained within a single file. Each message starts with a line matching `/^From /' and ends with a blank line. The folder architecture does not provide any persistantly stored current message variable, so the current message in this folder interface defaults to 1 and is not retained between opens of a folder. If the Timeout option is specified when the object is created, that value will be used to determine the timeout for attempting to aquire a folder lock. The default is 10 seconds. If the `DotLock' option is specified when the object is created, that value will be used to determine whether or not to use '`.lock'' style folder locking. The default value is 1. If the `Flock' option is specified when the object is created, that value will be used to determined whether or not to use flock style folder locking. By default, the option is not set. If the `NFSLock' option is specified when the object is created, that value will be used to determine whether or not special measures are taken when doing `DotLock'ing. These special measures consist of constructing the lock file in a special manner that is more immune to atomicity problems with NFS when creating a folder lock file. By default, the option is not set. This option necessitates the ability to use long filenames. It is currently a fatal error to have both `DotLock' and `Flock' disabled. **NOTE** flock locking is currently disabled until I can sift out the 'right way'. **NOTE** METHODS ======= open($folder_name) ------------------ * Call the superclass open method. * Check to see if it is a valid mbox folder. * Mark it as readonly if the folder is not writable. * Lock the folder. * Split the folder into individual messages in a temporary working directory. * Unlock the folder. * Cache all the headers. * Update the appropriate labels with information in the Status fields. * Set current_message to 1. close ----- Deletes the internal working copy of the folder and calls the superclass close method. sync ---- * Call the superclass sync method. * Lock the folder. * Extract into the temporary working directory any new messages that have been appended to the folder since the last time the folder was either opened or synced. * Create a new copy of the folder and populate it with the messages in the working copy that are not flagged for deletion and update the Status fields appropriately. * Move the original folder to a temp location * Move the new folder into place * Delete the old original folder * Unlock the folder pack ---- Calls the superclass pack method. Renames the message list to that there are no gaps in the numbering sequence. It also tweaks the current_message accordingly. get_message ($msg_number) Calls the superclass get_message method. Retrieves the given mail message file into a Mail::Internet object reference, sets the 'seen' label, and returns the reference. If the 'Content-Length' option is not set, then get_message will unescape 'From ' lines in the body of the message. get_message_file ($msg_number) Calls the superclass get_message_file method. Retrieves the given mail message file and returns the name of the file. Returns undef on failure. This method does NOT currently do any 'From ' unescaping. get_header($msg_number) ----------------------- If the particular header has never been retrieved then get_header loads (in a manner similar to get_message) the header of the given mail message into `$self->{Messages}{$msg_number}{Header}' and returns the object reference. If the header for the given mail message has already been retrieved in a prior call to get_header, then the cached entry is returned. It also calls the superclass get_header method. append_message($mref) --------------------- Calls the superclass `append_message' method. Creates a new mail message file, in the temporary working directory, with the contents of the mail message contained in `$mref'. It will synthesize a 'From ' line if one is not present in `$mref'. If the 'Content-Length' option is not set, then get_message will escape 'From ' lines in the body of the message. update_message($msg_number, $mref) ---------------------------------- Calls the superclass `update_message' method. Replaces the message pointed to by `$msg_number' with the contents of the Mail::Internet object reference `$mref'. It will synthesize a 'From ' line if one is not present in $mref. If the 'Content-Length' option is not set, then get_message will escape 'From ' lines in the body of the message. init ---- Initializes various items specific to *Mbox*. * Determines an appropriate temporary directory. If the TMPDIR environment variable is set, it uses that, otherwise it uses `/tmp'. The working directory will be a subdirectory in that directory. * Bumps a sequence number used for unique temporary filenames. * Initializes `$self->{WorkingDir}' to the name of a directory that will be used to hold the working copies of the messages in the folder. is_valid_folder_format($foldername) ----------------------------------- Returns 1 if the folder is a plain file and starts with the string '`From '', otherwise it returns 0. Returns 1 if the folder is a zero-length file and the `$Mail::Format::DefaultEmptyFileFormat' class variable is set to 'mbox'. Otherwise it returns 0. create($foldername) ------------------- Creates a new folder named `$foldername'. Returns 0 if the folder already exists, otherwise returns 1. AUTHOR ====== Kevin Johnson <`kjj@pobox.com'> COPYRIGHT ========= Copyright (c) 1996-1998 Kevin Johnson . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Folder/NNTP, Next: Mail/Freshmeat, Prev: Mail/Folder/Mbox, Up: Module List An NNTP folder interface for Mail::Folder. ****************************************** NAME ==== Mail::Folder::NNTP - An NNTP folder interface for Mail::Folder. *WARNING: This code is in alpha release. Expect the interface to change.* SYNOPSIS ======== `use Mail::Folder::NNTP;' DESCRIPTION =========== This module provides an interface to newsgroups accessible via the NNTP protocol. METHODS ======= open($foldername) ----------------- Populates the `Mail::Folder' object with information about the folder. The given foldername can be given one of two formats. Either `news://NEWSHOST/NEWSGROUP' where `NEWSHOST' is the nntp host and `NEWSGROUP' is the news group of interest, or `#news:NEWSGROUP' in which case the `NNTPSERVER' environment variable is referenced to determine the news host to connect to. Please note that it opens an NNTP connection for each open NNTP folder. If no Timeout option is specified, it defaults to a timeout of 120 seconds. * Call the superclass open method. * Make sure it is a valid NNTP foldername. * Connect to the NNTP server referenced in $foldername. * Perform an NNTP group command to determine quantity and range of articles available. * Loop through available article numbers, retrieve and cache the headers. * Set current_message to first_message. close ----- Calls the superclass get_message method and shuts down the connection to the NNTP server. sync ---- Currently a no-op and returns 0. Eventually will expunge articles marked as seen, look for new articles, update the `.newsrc' (or equivalent) file, and return the number of new articles found. pack ---- Since the association between article and article number is determined by the server, this method is a no-op. It return 1. get_message($msg_number) ------------------------ Calls the superclass get_message method. Retrieves the contents of the news article pointed to by the given `$msg_number' into a Mail::Internet object reference, caches the header, marks the message as 'seen', and returns the reference. It returns undef on failure. get_message_file($msg_number) ----------------------------- Not currently implemented. Returns undef. get_header($msg_number) ----------------------- If the particular header has never been retrieved then get_header retrieves the header for the given news article from the news server, converts it into a `Mail::Header' object and returns a reference to the object. If the header has already been retrieved in a prior call to get_header, then the cached entry is returned. It returns undef on failure. append_message($mref) --------------------- Not currently implemented. Returns 0. update_message($msg_number, $mref) ---------------------------------- Not currently implemented. Returns 0. is_valid_folder_format($foldername) ----------------------------------- Returns 1 if the foldername either starts with the string '`news://'' or starts with the string '`#news:'' and the `NNTPSERVER' environment variable is set, otherwise return 0; create($foldername) ------------------- Not currently implemented. Returns 0. AUTHOR ====== Kevin Johnson <`kjj@pobox.com'> COPYRIGHT ========= Copyright (c) 1997-1998 Kevin Johnson . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Freshmeat, Next: Mail/Header, Prev: Mail/Folder/NNTP, Up: Module List class for parsing e-mail newsletters from freshmeat.net ******************************************************* NAME ==== Mail::Freshmeat - class for parsing e-mail newsletters from freshmeat.net SYNOPSIS ======== $newsletter = new Mail::Freshmeat( \*STDIN ); $newsletter->parse; foreach my $entry (@{$newsletter->entries}) { print "Name: $entry->{name}"; print "Version: $entry->{version}; ... # Get an entry line as if it was from the first list # in the newsletter print $newsletter->short_entry($entry), "\n"; } DESCRIPTION =========== A subclass of Mail::Internet. This package provides parsing of the daily e-mail newsletters which are sent out from `http://freshmeat.net/' to any individual who requests them. METHODS ======= * parse $newsletter->parse; This method must be called before any accessors can be used. ACCESSORS ========= * *entry_keys* my @entry_keys = $newsletter->entry_keys; Returns the keys which each entry may have set, in the order in which they are encountered in the newsletter: - position - name_and_version - name - version - posted_on - license - category - homepage - download - changelog - body_type - body - changes - urgency - url * summary $summary = $self->summary; Returns the paragraph starting 'This is the official freshmeat newsletter ...'. * date $date = $self->date; Returns the date on which this newsletter was released. * total $total = $self->total; Returns the total number of entries in the newsletter. * entries Returns a reference to an array of hashes, each containing fully parsed information about an entry of the newsletter. The entries are in the original newsletter order. The keys of each hash will be a subset of the list returned by the entry_keys method. * *advertisement* $ad = $self->advertisement; Returns the '[ advertisement ]' section of the newsletter, which has one entry per line. * list $list = $self->list; Returns the '[ article list ]' section of the newsletter, which has one entry per line. * footer Returns the remainder of the newsletter following the '[ article details ]' section. * details Returns the '[ article details ]' sections of the newsletter, which has each entry in full. * *short_entry* $list1 = $newsletter->list; $list2 = join '', map { 'o ' . $newsletter->short_entry($_) . "\n" } @{$newsletter->entries}; if ($list1 ne $list2) { die "Oh no! Mail::Freshmeat doesn't do what it claims!"; } :-) What, that's not real documentation? Bah. Alright then. This method returns the entry in exactly the same format as when it was one of the lines beginning with 'o ' in the original newsletter, minus the actual 'o ' bit. So, you can regenerate the entire '[ article list ]' section (in a new order, if you want) using something similar to the example above. * *entry_header* This method returns the entry's "header" (from the line starting 'name:' to the line starting 'changelog:' (or to the line where 'changelog:' would have been if it was there)) in exactly the same format (modulo whitespace) as when it was one of the entries in the '[ article details ]' section of the original newsletter. * *entry_body* This method returns the entry's "body" - everything following the entry's "header" as returned by `entry_header'. * *long_entry* $list1 = $newsletter->details; $list2 = join $newsletter->divider, map { $newsletter->long_entry($_) } @{$newsletter->entries}; # $list1 and $list2 should now be identical(ish) modulo whitespace This method returns the entry in exactly the same format (modulo whitespace differences) as when it was one of the entries in the '[ article details ]' section of the original newsletter. So, you can regenerate that entire section (in a new order, if you want) using something similar to the example above. All this method actually does is concatenate the results of the `entry_header' and `entry_body' methods. * *divider* print $newsletter->divider; Returns one of those fancy '--- - --- ------ - --- -- - - - -- -' dividers. * *ad_header* print $newsletter->ad_header; Returns the text for starting the advertisement section. * *list_header* print $newsletter->list_header; Returns the text for starting the article list section. * *details_header* print $newsletter->details_header; Returns the text for starting the article details section. AUTHOR ====== Adam Spiers LICENSE ======= All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. VERSION ======= This is release 0.91. SEE ALSO ======== perl(1).  File: pm.info, Node: Mail/Header, Next: Mail/IMAPClient, Prev: Mail/Freshmeat, Up: Module List manipulate mail RFC822 compliant headers **************************************** NAME ==== Mail::Header - manipulate mail RFC822 compliant headers SYNOPSIS ======== use Mail::Header; $head = new Mail::Header; $head = new Mail::Header \*STDIN; $head = new Mail::Header [<>], Modify => 0; DESCRIPTION =========== This package provides a class object which can be used for reading, creating, manipulating and writing RFC822 compliant headers. CONSTRUCTOR =========== new ( [ ARG ], [ OPTIONS ] ) ARG may be either a file descriptor (reference to a GLOB) or a reference to an array. If given the new object will be initialized with headers either from the array of read from the file descriptor. OPTIONS is a list of options given in the form of key-value pairs, just like a hash table. Valid options are Modify If this value is *true* then the headers will be re-formatted, otherwise the format of the header lines will remain unchanged. MailFrom This option specifies what to do when a header in the form `From ' is encountered. Valid values are `IGNORE' - ignore and discard the header, ERROR - invoke an error (call die), `COERCE' - rename them as Mail-From and `KEEP' - keep them. FoldLength The default length of line to be used when folding header lines METHODS ======= modify ( [ VALUE ] ) If VALUE is false then `Mail::Header' will not do any automatic reformatting of the headers, other than to ensure that the line starts with the tags given. mail_from ( OPTION ) OPTION specifies what to do when a ``From '' line is encountered. Valid values are `IGNORE' - ignore and discard the header, ERROR - invoke an error (call die), `COERCE' - rename them as Mail-From and `KEEP' - keep them. fold ( [ LENGTH ] ) Fold the header. If LENGTH is not given then `Mail::Header' uses the following rules to determine what length to fold a line. The fold length for the tag that is begin processed The default fold length for the tag that is being processed The default fold length for the object extract ( ARRAY_REF ) Extract a header from the given array. extract *will modify* this array. Returns the object that the method was called on. read ( FD ) Read a header from the given file descriptor. empty () Empty the `Mail::Header' object of all lines. header ( [ ARRAY_REF ] ) header does multiple operations. First it will extract a header from the array, if given. It will the reformat the header, if reformatting is permitted, and finally return a reference to an array which contains the header in a printable form. header_hashref ( [ HASH_REF ] ) As header, but it will eventually set headers from a hash reference, and it will return the headers as a hash reference. The values in the hash might either be a scalar or an array reference, as an example: $hashref->{From}='Tobias Brox '; $hashref->{To}=['you@somewhere', 'me@localhost']; add ( TAG, LINE [, INDEX ] ) Add a new line to the header. If TAG is undef the the tag will be extracted from the beginning of the given line. If INDEX is given the new line will be inserted into the header at the given point, otherwise the new line will be appended to the end of the header. replace ( TAG, LINE [, INDEX ] ) Replace a line in the header. If TAG is undef the the tag will be extracted from the beginning of the given line. If INDEX is given the new line will replace the Nth instance of that tag, otherwise the first instance of the tag is replaced. If the tag does not appear in the header then a new line will be appended to the header. combine ( TAG [, WITH ] ) Combine all instances of TAG into one. The lines will be joined togther with WITH, or a single space if not given. The new item will be positioned in the header where the first instance was, all other instances of will be removed. get ( TAG [, INDEX ] ) Get the text form a line. If INDEX is given then the text of the Nth instance will be returned. If it is not given the return value depends on the context in which get was called. In an array context a list of all the text from all the instances of TAG will be returned. In a scalar context the text for the first instance will be returned. delete ( TAG [, INDEX ] ) Delete a tag from the header. If INDEX id given then the Nth instance of the tag will be removed. If INDEX is not given all instances of tag will be removed. count ( TAG ) Returns the number of times the given atg appears in the header print ( [ FD ] ) Print the header to the given file descriptor, or STDOUT if no file descriptor is given. as_string () Returns the header as a single string. fold_length ( [ TAG ], [ LENGTH ] ) Set the default fold length for all tags or just one. With no arguments the default fold length is returned. With two arguments it sets the fold length for the given tag and returns the previous value. If only LENGTH is given it sets the default fold length for the current object. In the two argument form fold_length may be called as a static method, setting default fold lengths for tags that will be used by all `Mail::Header' objects. See the fold method for a description on how `Mail::Header' uses these values. tags () Retruns an array of all the tags that exist in the header. Each tag will only appear in the list once. The order of the tags is not specified. dup () Create a duplicate of the current object. cleanup () Remove any header line that, other than the tag, only contains whitespace unfold ( [ TAG ] ) Unfold all instances of the given tag so that they do not spread across multiple lines. IF TAG is not given then all lines are unfolded. AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1995-7 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/IMAPClient, Next: Mail/Internet, Prev: Mail/Header, Up: Module List An IMAP Client API ****************** NAME ==== Mail::IMAPClient - An IMAP Client API SYNOPSIS ======== use Mail::IMAPClient; my $imap = Mail::IMAPClient->new( Server => 'imaphost', User => 'memememe', Password => 'secret', ); $imap->Debug($opt_d); my @folders = $imap->folders; foreach my $f (@folders) { print "$f is a folder with ", $imap->message_count($f), " messages.\n"; } DESCRIPTION =========== This module provides methods implementing the IMAP protocol. It allows perl scripts to interact with IMAP message stores. The module is used by constructing or instantiating a new IMAPClient object via the new constructor method. Once the object has been instantiated, the connect method is either implicitly or explicitly called. At that point methods are available that implement the IMAP client commands as specified in *RFC2060*. When processing is complete, the *logoff* object method is called, either explicitly by the program or implicitly when the object goes out of scope (or at program termination). This documentation is not meant to be a replacement for RFC2060, and the wily programmer will have a copy of that document handy when coding IMAP clients. Note that this documentation uses the term folder in place of RFC2060's use of mailbox. This documentation reserves the use of the term mailbox to refer to the set of folders owned by a specific IMAP id. RFC2060 defines four possible states for an IMAP connection: not authenticated, authenticated, selected, and logged out. These correspond to the *IMAPClient* constants *Connected*, Authenticated, Selected, and *Unconnected*, respectively. These constants are implemented as class methods, and can be used in conjunction with the Status method to determine the status of an *IMAPClient* object and its underlying IMAP session. Note that an *IMAPClient* object can be in the *Unconnected* state both before a server connection is made and after it has ended. This differs slightly from RFC2060, which does not define a pre-connection status. For a discussion of the methods available for examining the *IMAPClient* object's status, see the section labeled "Status Methods", below. Errors ------ If you attempt an operation that results in an error, then you can retrieve the text of the error message by using the *LastError* method. However, since the *LastError* method is an object method (and not a class method) you will only be able to use this method if you've successfully created your object. Errors in the new method can prevent your object from ever being created. Additionally, if you supply the Server, User, and Password parameters to new, it will attempt to call connect and login, either of which could fail and cause your new method call to return undef (in which case your object will have been created but its reference will have been discarded before ever being returned to you). If this happens to you, you can always check `$@'. *Mail::IMAPClient* will populate that variable with something useful if either of the new, connect, or login methods fail. In fact, as of version 2, the `$@' variable will always contain error info from the last error, so you can print that instead of calling *LastError* if you wish. If you run your script with warnings turned on (which I'm sure you'll do at some point because it's such a good idea) then any error message that gets placed into the *LastError* slot (and/or in `$@') will automatically generate a warning. Transactions ------------ RFC2060 requires that each line in an IMAP conversation be prefixed with a tag. A typical conversation consists of the client issuing a tag-prefixed command string, and the server replying with one of more lines of output. Those lines of output will include a command completion status code prefixed by the same tag as the original command string. The *IMAPClient* module uses a simple counter to ensure that each client command is issued with a unique tag value. This tag value is referred to by the *IMAPClient* module as the transaction number. A history is maintained by the *IMAPClient* object documenting each transaction. The Transaction method returns the number of the last transaction, and can be used to retrieve lines of text from the object's history. The Clear parameter is used to control the size of the session history so that long-running sessions do not eat up unreasonable amounts of memory. See the discussion of Clear under `"parameters"' in this node for more information. The *Report* transaction returns the history of the entire IMAP session since the initial connection or for the last Clear transactions. This provides a record of the entire conversation, including client command strings and server responses, and is a wonderful debugging tool as well as a useful source of raw data for custom parsing. Class Methods ------------- There are a couple of methods that can be invoked as class methods. Generally they can be invoked as an object method as well, as a convenience to the programmer. (That is, as a convenience to the programmer who wrote this module, as well as the programmers using it. It's easier not to enforce a class method's classiness.) Note that if the new method is called as an object method, the object returned is identical to what have would been returned if new had been called as a class method. It doesn't give you a copy of the original object or anything like that. new() The new method creates a new instance of an *IMAPClient* object. If the Server parameter is passed as an argument to new, then new will implicitly call the connect method, placing the new object in the *Connected* state. If User and Password values are also provided, then connect will in turn call login, and the resulting object will be returned from new in the Authenticated state. If the Server parameter is not supplied then the *IMAPClient* object is created in the *Unconnected* state. If the new method is passed arguments then those arguments will be treated as a list of key=>value pairs. The key should be one of the parameters as documented under `"parameters"' in this node, below. Here are some examples: use Mail::IMAPClient; my $imap = Mail::IMAPClient->new; # returns an unconnected Mail::IMAPClient object # ... # intervening code using the 1st object, then: $imap = Mail::IMAPClient->new( # returns a new, authenticated Mail::IMAPClient object Server => $host, User => $id, Password=> $pass, Clear => 5, # Unnecessary since '5' is the default # ... # Other key=>value pairs go here ) or die "Cannot connect to $host as $id: $@"; See also `"parameters"' in this node, below, and `"connect"' in this node and `"login"' in this node for information on how to manually connect and login after new. Unconnected() returns a value equal to the numerical value associated with an object in the *Unconnected* state. Connected() returns a value equal to the numerical value associated with an object in the *Connected* state. Authenticated() returns a value equal to the numerical value associated with an object in the Authenticated state. Selected() returns a value equal to the numerical value associated with an object in the Selected state. Strip_cr() The *Strip_cr* method strips carriage returns from IMAP client command output. Although RFC2060 specifies that lines in an IMAP conversation end with , it is often cumbersome to have the carriage returns in the returned data. This method accepts one or more lines of text as arguments, and returns those lines with all sequences changed to . Any input argument with no carriage returns is returned unchanged. If the first argument (not counting the class name or object reference) is an array reference, then members of that array are processed as above and subsequent arguments are ignored. If the method is called in scalar context then an array reference is returned instead of an array of results. Taken together, these last two lines mean that you can do something like: my @list = $imap->some_imap_method ; @list = $imap->Strip_cr(@list) ; # or: my $list = [ $imap->some_imap_method ] ; # returns an array ref $list = $imap->Strip_cr($list); *NOTE: Strip_cr* does not remove new line characters. Rfc2060_date() The *Rfc2060_date* method accepts one input argument, a number of seconds since the epoch date. It returns an RFC2060 compliant date string for that date (as required in date-related arguments to SEARCH, such as "since", "before", etc.). Rfc822_date() The *Rfc822_date* method accepts one input argument, a number of seconds since the epoch date. It returns an RFC822 compliant date string for that date (without the 'Date:' prefix). Useful for putting dates in message strings before calling append. Parameters ---------- There are several parameters that influence the behavior of an *IMAPClient* object. Each is set by specifying a named value pair during new method invocation as follows: my $imap = Mail::IMAPClient->new ( parameter => "value", parameter2 => "value", ... ); Parameters can also be set after an object has been instantiated by using the parameter's eponymous accessor method like this: my $imap = Mail::IMAPClient->new; $imap->parameter( "value"); $imap->parameter2("value"); The eponymous accessor methods can also be used without arguments to obtain the current value of the parameter as follows: my $imap = Mail::IMAPClient->new; $imap->parameter( "value"); $imap->parameter2("value"); ... # A whole bunch of awesome perl code, # omitted for brevity my $forgot = $imap->parameter; my $forgot2 = $imap->parameter2; Note that in these examples I'm using 'parameter' and 'parameter2' as generic parameter names. The *IMAPClient* object doesn't actually have parameters named 'parameter' and 'parameter2'. On the contrary, the available parameters are: Clear() The name of this parameter, for historical reasons, is somewhat misleading. It should be named *Wrap*, because it specifies how many transactions are stored in the wrapped history buffer. But it didn't always work that way; the buffer used to actually get cleared. The name though remains the same in the interests of backwards compatibility. Clear specifies that the object's history buffer should be wrapped after every n transactions, where n is the value specified for the Clear parameter. Calling the eponymous Clear method without an argument will return the current value of the Clear parameter but will not cause clear the history buffer to wrap. Setting Clear to 0 turns off automatic history buffer wrapping, and setting it to 1 turns off the history buffer facility (except for the last transaction, which cannot be disabled without breaking the *IMAPClient* module). Setting Clear to 0 will not cause an immediate clearing of the history buffer; setting it to 1 (or any other number) will (except of course for that inevitable last transaction). The default Clear value is set to five in order to conserve memory. Debug() Sets the debugging flag to either a true or false value. Can be supplied with the new method call or separately by calling the Debug object method. Use of this parameter is strongly recommended when debugging scripts and required when reporting bugs. Debug_fh() Specifies the filehandle to which debugging information should be printed. It can either a filehandle object reference or a filehandle glob. The default is to print debugging info to STDERR. For example, you can: use Mail::IMAPClient; use IO::File; # set $user, $pass, and $server here my $dh = IO::File->new(">debugging.output") or die "Can't open debugging.output: $!\n"; my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass, Server=>$server, Debug=> "yes, please", Debug_fh => $dh ); Or you can: use Mail::IMAPClient; # set $user, $pass, and $server here open(DBG,">debugging.output") or die "Can't open debugging.output: $!\n"; my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG ); Folder() The *Folder* parameter returns the name of the currently-selected folder (in case you forgot). It can also be used to set the name of the currently selected folder, which is completely unnecessary if you used the select method (or select's read-only equivalent, the *examine* method) to select it. Note that setting the *Folder* parameter does not automatically select a new folder; you use the select or *examine* object methods for that. Generally, the *Folder* parameter should only be queried (by using the no-argument form of the *Folder* method). You will only need to set the *Folder* parameter if you use some mysterious technique of your own for selecting a folder, which you probably won't do. Password() Specifies the password to use when logging into the IMAP service on the host specified in the Server parameter as the user specified in the User parameter. Can be supplied with the new method call or separately by calling the Password object method. If Server, User, and Password are all provided to the new method, then the newly instantiated object will be connected to the host specified in Server (at either the port specified in Port or the default port 143) and then logged on as the user specified in the User parameter (using the password provided in the Password parameter). See the discussion of the new method, below. Peek() Setting *Peek* to a true value will prevent the *body_string*, *message_string* and *message_to_file* methods from automatically setting the *\Seen* flag. Setting *Peek* to 0 (zero) will force *body_string*, *message_string*, *message_to_file*, and *parse_headers* to always set the *\Seen* flag. The default is to set the seen flag whenever you fetch the body of a message but not when you just fetch the headers. Passing undef to the eponymous *Peek* method will reset the *Peek* parameter to its pristine, default state. Port() Specifies the port on which the IMAP server is listening. The default is 143, which is the standard IMAP port. Can be supplied with the new method call or separately by calling the Port object method. Server() Specifies the hostname or IP address of the host running the IMAP server. If provided as part of the new method call, then the new IMAP object will automatically be connected at the time of instantiation. (See the new method, below.) Can be supplied with the new method call or separately by calling the Server object method. Socket() The Socket method can be used to obtain the socket handle of the current connection (say, to do I/O on the connection that is not otherwise supported by *Mail::IMAPClient*) or to replace the current socket with a new handle (perhaps an SSL handle, for example). If you supply a socket handle yourself, either by doing something like: $imap=Mail::IMAPClient->new(Socket=>$sock, User => ... ); or by doing something like: $imap=Mail::IMAPClient->new(User => $user, Password => $pass, Server => $host); # blah blah blah $imap->Socket($ssl); then it will be up to you to establish the connection AND to authenticate, either via the login method, or the fancier authenticate, or, since you know so much anyway, by just doing raw I/O against the socket until you're logged in. If you do any of this then you should also set the State parameter yourself to reflect the current state of the object (i.e. Connected, Authenticated, etc). Timeout() Specifies the timeout value in seconds for reads. Specifying a true value for Timeout will prevent *Mail::IMAPClient* from blocking in a read. Since timeouts are implemented via the perl select operator, the Timeout parameter may be set to a fractional number of seconds. Not supplying a Timeout, or (re)setting it to zero, disables the timeout feature. Uid() If *Uid* is set to a true value (i.e. 1) then the behavior of the fetch, search, copy, and store methods (and their derivatives) is changed so that arguments that would otherwise be message sequence numbers are treated as message UID's and so that return values (in the case of the search method and its derivatives) that would normally be message sequence numbers are instead message UID's. Internally this is implemented as a switch that, if turned on, causes methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH, or UID COPY, respectively. The main difference between message sequence numbers and message UID's is that, according to RFC2060, UID's must not change during a session and should not change between sessions, and must never be reused. Sequence numbers do not have that same guarantee and in fact may be reused right away. Since foldernames also have a unique identifier (UIDVALIDITY), which is provided when the folder is selected or *examine*d or by doing something like "$imap->status($folder,"UIDVALIDITY"), it is possible to uniquely identify every message on the server, although normally you won't need to bother. The methods currently affected by turning on the *Uid* flag are: copy fetch search store message_string message_uid body_string flags move size parse_headers Note that if for some reason you only want the *Uid* parameter turned on for one command, then you can choose between the following two snippets, which are equivalent: Example 1: $imap->Uid(1); my @uids = $imap->search('SUBJECT',"Just a silly test"); # $imap->Uid(0); Example 2: my @uids; foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") { chomp $r; $r =~ s/\r$//; $r =~ s/^\*\s+SEARCH\s+// or next; push @uids, grep(/\d/,(split(/\s+/,$r))); } In the second example, we used the default method to issue the UID IMAP Client command, being careful to use an all-uppercase method name so as not to inadvertently call the *Uid* accessor method. Then we parsed out the message UIDs manually, since we don't have the benefit of the built-in search method doing it for us. Please be very careful when turning the *Uid* parameter on and off throughout a script. If you loose track of whether you've got the *Uid* parameter turned on you might do something sad, like deleting the wrong message. Remember, like all eponymous accessor methods, the *Uid* method without arguments will return the current value for the *Uid* parameter, so do yourself a favor and check. The safest approach is probably to turn it on at the beginning and then leave it on. (Remember that leaving it turned off can lead to problems if changes to a folder's contents cause resequencing.) By default, the *Uid* parameter is turned on. User() Specifies the userid to use when logging into the IMAP service. Can be supplied with the new method call or separately by calling the User object method. Parameters can be set during new method invocation by passing named parameter/value pairs to the method, or later by calling the parameter's eponymous object method. Object Methods -------------- Object methods must be invoked against objects created via the new method. They cannot be invoked as class methods, which is why they are "object methods" and not "class methods". There are basically two types of object methods-those that participate in the IMAP session's conversation (i.e. they issue IMAP client commands) and those that do not. Methods that do not result in new IMAP client commands being issued (such as the *Transaction, Status*, and History methods) all begin with an uppercase letter, to distinguish themselves from methods that do correspond to IMAP client commands. (Class methods and eponymous parameter methods likewise begin with an uppercase letter because they also do not correspond to an IMAP client command.) The *IMAPClient* object methods are: append() The append method adds a message to the specified folder. It takes two arguments, the name of the folder to append the message to, and the text of the message (including headers). Additional arguments are added to the message text, separated with . The append method returns the UID of the new message (a true value) if successful, or undef if not, if the IMAP server has the UIDPLUS capability. If it doesn't then you just get true on success and undef on failure. Note that many servers will get really ticked off if you try to append a message that contains "bare newlines", which is the titillating term given to newlines that are not preceded by a carrage return. To protect against this, append will insert a carrage return before any newline that is "bare". If you don't like this behavior then you can avoid it by not passing naked newlines to append. append_file() The *append_file* method adds a message to the specified folder. It takes two arguments, the name of the folder to append the message to, and the file name of an RFC822-formatted message. An optional third argument is the value to use for input_record_separator. The default is to use "" for the first read (to get the headers) and "\n" for the rest. Any valid value for $/ is acceptable, even the funky stuff, like `\1024'. (See *Note Perlvar: (perl.info)perlvar, for more information on $/). The *append_file* method returns the UID of the new message (a true value) if successful, or undef if not, if the IMAP server has the UIDPLUS capability. If it doesn't then you just get true on success and undef on failure. If you supply a filename that doesn't exist then you get an automatic undef. The *LastError* method will remind you of this if you forget that your file doesn't exist but somehow manage to remember to check *LastError*. In case you're wondering, *append_file* is provided mostly as a way to allow large messages to be appended without having to have the whole file in memory. It uses the -s operator to obtain the size of the file and then reads and sends the contents line by line (or not, depending on whether you supplied that optional third argument). authenticate() The authenticate method accepts two arguments, an authentication type to be used (ie CRAM-MD5) and a code or subroutine reference to execute to obtain a response. The authenticate assumes that the authentication type specified in the first argument follows a challenge-response flow. The authenticate method issues the IMAP Client AUTHENTICATE command and receives a challenge from the server. That challenge (minus any tag prefix or enclosing '+' characters but still in the original base64 encoding) is passed as the only argument to the code or subroutine referenced in the second argument. The return value from the 2nd argument's code is written to the server as is, except that a sequence is appended if neccessary. before() The before method works just like the `"since"' in this node method, below, except it returns a list of messages whose internal system dates are before the date supplied as the argument to the before method. body_string() The *body_string* method accepts a message sequence number (or a message UID, if the *Uid* parameter is set to true) as an argument and returns the message body as a string. The returned value contains the entire message in one scalar variable, without the message headers. capability() The capability method returns an array of capabilities as returned by the CAPABILITY IMAP Client command, or a reference to an array of capabilities if called in scalar context. If the CAPABILITY IMAP Client command fails for any reason then the capability method will return undef. close() The close method is implemented via the default method and is used to close the currently selected folder via the CLOSE IMAP client command. According to RFC2060, the CLOSE command performs an implicit EXPUNGE, which means that any messages that you've flagged as *\Deleted* (say, with the *delete_message* method) will now be deleted. If you haven't deleted any messages then close can be thought of as an "unselect". See also *delete_message*, expunge, and your tattered copy of RFC2060. connect() The connect method connects an imap object to the server. It returns undef if it fails to connect for any reason. If values are available for the User and Password parameters at the time that connect is invoked, then connect will call the login method after connecting and return the result of the login method to connect's caller. If either or both of the User and Password parameters are unavailable but the connection to the server succeeds then connect returns a pointer to the *IMAPClient* object. The Server parameter must be set (either during new method invocation or via the Server object method) before invoking connect. If the Server parameter is supplied to the new method then connect is implicitly called during object construction. The connect method sets the state of the object to connected if it successfully connects to the server. copy() The copy method requires a folder name as the first argument, and a list of one or more messages sequence numbers (or messages UID's, if the UID parameter is set to a true value). The message sequence numbers or UID's should refer to messages in the currenly selected folder. Those messages will be copied into the folder named in the first argument. The copy method returns undef on failure and a true value if successful. If the server to which the current Mail::IMAPClient object is connected supports the UIDPLUS capability then the true value returned by copy will be a comma separated list of UID's, which are the UID's of the newly copied messages in the target folder. delete_message() The *delete_message* method accepts a list of arguments. If the *Uid* parameter is not set to a true value, then each item in the list should be either: > a message sequence number, > a comma-separated list of message sequence numbers, > a reference to an array of message sequence numbers, or If the *Uid* parameter is set to a true value, then each item in the list should be either: > a message UID, > a comma-separated list of UID's, or > a reference to an array of message UID's. The messages identified by the sequence numbers or UID's will be deleted. *delete_message* returns the number of messages it was told to delete. However, since the delete is done by issuing the *+FLAGS.SILENT* option of the STORE IMAP client command, there is no guarantee that the delete was successful for every message. In this manner the *delete_message* method sacrifices accuracy for speed. If you must have guaranteed results then use the IMAP STORE client command (via the default method) and use the +FLAGS (\Deleted) option, and then parse your results manually. Eg: $imap->store($msg_id,'+FLAGS (\Deleted)'); my @results = $imap->History($imap->Transaction); ... # code to parse output goes here The *IMAPClient* object must be in Selected status to use the *delete_message* method. NOTE: All the messages identified in the input argument(s) must be in the currently selected folder. Failure to comply to this requirement will almost certainly result in the wrong message(s) being deleted. This would be a crying shame. *NOTE SOME MORE:* In the grand tradition of the IMAP protocol, deleting a message doesn't actually delete the message. Really. If you want to make sure the message has been deleted, you need to expunge the folder (via the expunge method, which is implemented via the default method). Or at least close it. This is generally considered a feature, since after deleting a message, you can change your mind and undelete it at any time before your expunge or close. *See also:* The delete method, to delete a folder, the expunge method, to expunge a folder, the *restore_message* method to undelete a message, and the close method (implemented here via the default method) to close a folder. Oh, and don't forget about RFC2060. deny_seeing() The *deny_seeing* method accepts a list of one or more message sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then unsets the "\Seen" flag for those messages. Of course, if the *Uid* parameter is set to a true value then those message sequence numbers had better be unique message id's, but then you already knew that, didn't you? Note that specifying `$imap-'deny_seeing(@msgs)> is just a shortcut for specifying `$imap-'unset_flag("Seen",@msgs)>. disconnect() Disconnects the *IMAPClient* object from the server. Functionally equivalent to the logout method. examine() The *examine* method selects a folder in read-only mode and changes the object's state to "Selected". The folder selected via the *examine* method can be examined but no changes can be made unless it is first selected via the select method. The *examine* method accepts one argument, which is the name of the folder to select. exists() Accepts one argument, a folder name. Returns true if the folder exists or false if it does not exist. expunge() The expunge method accepts one optional argument, a folder name. It expunges the folder specified as the argument, or the currently selected folder if no argument is supplied. Although RFC2060 does not permit optional arguments (like a folder name) to the EXPUNGE client command, the expunge method does, which is especially interesting given that the expunge method doesn't technically exist. In case you're curious, expunging a folder deletes the messages that you thought were already deleted via *delete_message* but really weren't, which means you have to use a method that doesn't exist to delete messages that you thought didn't exist. (Seriously, I'm not making any of this stuff up.) Or you could use the close method, which de-selects as well as expunges and which likewise doesn't technically exist. As with any IMAP client command, that fact that these methods don't exist will not stop them from working anyway. This is a feature of the *Mail::IMAPClient* module. (See `"Other IMAP Client Commands and the Default Method"' in this node if you still don't believe me.) fetch() The fetch method implements the FETCH IMAP client command. It accepts a list of arguments, which will be converted into a space-delimited list of arguments to the FETCH IMAP client command. If no arguments are supplied then fetch does a FETCH ALL. If the *Uid* parameter is set to a true value then the first argument will be treated as a UID or list of UID's, which means that the UID FETCH IMAP client command will be run instead of FETCH. (It would really be a good idea at this point to review RFC2060.) If called in array context, fetch will return an array of output lines. The output lines will be returned just as they were received from the server, so your script will have to be prepared to parse out the bits you want. The only exception to this is literal strings, which will be inserted into the output line at the point at which they were encountered (without the {nnn} literal field indicator). See RFC2060 for a description of literal fields, and don't blame me if you're still confused by them. (I read that rfc just about every day and didn't really understand those literal fields for about a year.) If fetch is called in a scalar context, then a reference to an array (as described above) is returned instead of the entire array. flags() The flags method implements the FETCH IMAP client command to list a single message's flags. It accepts one argument, a message sequence number (or a message UID, if the *Uid* parameter is true), and returns an array (or a reference to an array, if called in scalar context) listing the flags that have been set. Flag names are provided with leading backslashes. As of version 1.11, you can supply either a list of message id's or a reference to an array of of message id's (which means either sequence number, if the Uid parameter is false, or message UID's, if the Uid parameter is true) instead of supplying a single message sequence number or UID. If you do, then the return value will not be an array or array reference; instead, it will be a hash reference, with each key being a message sequence number (or UID) and each value being a reference to an array of flags set for that message. For example, if you want to display the flags for every message in the folder where you store e-mail related to your plans for world domination, you could do something like this: use Mail::IMAPClient; my $imap = Mail::IMAPClient->new( Server => $imaphost, User => $login, Password=> $pass, Uid => 1, # optional ); $imap->select("World Domination"); # get the flags for every message in my 'World Domination' folder $flaghash = $imap->flags( scalar($imap->search("ALL"))) ; # pump through sorted hash keys to print results: for my $k (sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash) { # print: Message 1: \Flag1, \Flag2, \Flag3 print "Message $k:\t",join(", ",@{$flaghash->{$k}}),"\n"; } folders() The *folders* method returns an array listing the available folders. It will only be successful if the object is in the Authenticated or Selected states. has_capability() Returns true if the IMAP server to which the *IMAPClient* object is connected has the capability specified as an argument to *has_capability*. internaldate() *internaldate* accepts one argument, a message id (or UID if the Uid parameter is true), and returns that message's internal date. is_parent() The *is_parent* method accepts one argument, the name of a folder. It returns a value that indicates whether or not the folder has children. The value it returns is either 1) a true value (indicating that the folder has children), 2) 0 if the folder has no children at this time, or 3) undef if the folder is not permitted to have children. Eg: my $parenthood = $imap->is_parent($folder); if (defined($parenthood)) { if ($parenthood) { print "$folder has children.\n" ; } else { print "$folder is permitted children, but has none.\n"; } } else { print "$folder is not permitted to have children.\n"; } list() The list method implements the IMAP LIST client command. Arguments are passed to the IMAP server as received, separated from each other by spaces. If no arguments are supplied then the default list command `tag LIST "" '*'' is issued. The list method returns an array (or an array reference, if called in a scalar context). The array is the unaltered output of the LIST command. (If you want your output altered then see the *folders* method, above.) login() The login method uses the IMAP LOGIN client command (as defined in RFC2060) to log into the server. The User and Password parameters must be set before the login method can be invoked. If successful, the login method returns a pointer to the *IMAPClient* object and sets the object status to Authenticated. If unsuccessful, it returns undef. logout() The logout method issues the LOGOUT IMAP client commmand. Since the LOGOUT IMAP client command causes the server to end the connection, this also results in the *IMAPClient* client entering the *Unconnected* state. This method does not, however, destroy the *IMAPClient* object, so a program can re-invoke the connect and login methods if it wishes to reestablish a session later in the program. lsub() The *lsub* method implements the IMAP LSUB client command. Arguments are passed to the IMAP server as received, separated from each other by spaces. If no arguments are supplied then the default lsub command `tag LSUB "" '*'' is issued. The *lsub* method returns an array (or an array reference, if called in a scalar context). The array is the unaltered output of the LSUB command. If you want an array of subscribed folders then see the *subscribed* method, below. message_count() The *message_count* method accepts the name of a folder as an argument and returns the number of messages in that folder. Internally, it invokes the status method (see above) and parses out the results to obtain the number of messages. If you don't supply an argument to *message_count* then it will return the number of messages in the currently selected folder (assuming of course that you've used the select or *examine* method to select it instead of trying something funky). message_string() The *message_string* method accepts a message sequence number (or message UID if *Uid* is true) as an argument and returns the message as a string. The returned value contains the entire message in one scalar variable, including the message headers. Note that using this method will set the message's "\Seen" flag as a side effect, unless *Peek* is set to a true value. message_to_file() The *message_to_file* method accepts a filename or file handle and one or more message sequence numbers (or message UIDs if *Uid* is true) as arguments and places the message string(s) (including RFC822 headers) into the file named in the first argument (or prints them to the filehandle, if a filehandle is passed). The returned value is true on succes and undef on failure. If the first argument is a reference, it is assumed to be an open filehandle and will not be closed when the method completes, If it is a file, it is opened in append mode, written to, then closed. Note that using this method will set the message's "\Seen" flag as a side effect. But you can use the *deny_seeing* method to set it back, or set the *Peek* parameter to a true value to prevent setting the "\Seen" flag at all. This method currently works by making some basic assumptions about the server's behavior, notably that the message text will be returned as a literal string but that nothing else will be. If you have a better idea then I'd like to hear it. message_uid() The *message_uid* method accepts a message sequence number (or message UID if *Uid* is true) as an argument and returns the message's UID. Yes, if *Uid* is true then it will use the IMAP UID FETCH UID client command to obtain and return the very same argument you supplied. This is an IMAP feature so don't complain to me about it. move() The move method moves messages from the currently selected folder to the folder specified in the first argument to move. If the *Uid* parameter is not true, then the rest of the arguments should be either: > a message sequence number, > a comma-separated list of message sequence numbers, or > a reference to an array of message sequence numbers. If the *Uid* parameter is true, then the arguments should be: > a message UID, > a comma-separated list of message UID's, or > a reference to an array of message UID's. If the target folder does not exist then it will be created. If move is sucessful, then it returns a true value. Furthermore, if the *Mail::IMAPClient* object is connected to a server that has the UIDPLUS capability, then the true value will be the comma-separated list of UID's for the newly copied messages. The list will be in the order in which the messages were moved. (Since move uses the copy method, the messages will be moved in numerical order.) If the move is not successful then move returns undef. Note that a move really just involves copying the message to the new folder and then setting the *\Deleted* flag. To actually delete the original message you will need to run expunge (or close). namespace() The namespace method runs the NAMESPACE IMAP command (as defined in RFC 2342). When called in a list context, it returns a list of three references. Each reference looks like this: [ [ $prefix_1, $separator_1 ] , [ $prefix_2, $separator_2], [ $prefix_n , $separator_n] ] The first reference provides a list of prefices and separator charactors for the available personal namespaces. The second reference provides a list of prefices and separator charactors for the available shared namespaces. The third reference provides a list of prefices and separator charactors for the available public namespaces. If any of the three namespaces are unavailable on the current server then an 'undef' is returned instead of a reference. So for example if shared folders were not supported on the server but personal and public namespaces were both available (with one namespace each), the returned value might resemble this: ( [ "", "/" ] , undef, [ "#news", "." ] ) ; If the namespace method is called in scalar context, it returns a reference to the above-mentioned list of three references, thus creating a single structure that would pretty-print something like this: $VAR1 = [ [ [ $user_prefix_1, $user_separator_1 ] , [ $user_prefix_2, $user_separator_2], [ $user_prefix_n , $user_separator_n] ] , # or undef [ [ $shared_prefix_1, $shared_separator_1 ] , [ $shared_prefix_2, $shared_separator_2], [ $shared_prefix_n , $shared_separator_n] ] , # or undef [ [ $public_prefix_1, $public_separator_1 ] , [ $public_prefix_2, $public_separator_2], [ $public_prefix_n , $public_separator_n] ] , # or undef ]; Or, to look at our previous example (where shared folders are unsupported) called in scalar context: $VAR1 = [ [ [ "" , "/", ], ], undef, [ [ "#news", "." ], ], ]; on() The *on* method works just like the *since* method, below, except it returns a list of messages whose internal system dates are the same as the date supplied as the argument. =item parse_headers () The *parse_headers* method accepts as arguments a message sequence number and a list of header fields. It returns a hash reference in which the keys are the header field names (without the colon) and the values are references to arrays of values. A picture would look something like this: $hashref = $imap->parse_headers(1,"Date","Received","Subject","To"); $hashref = { "Date" => [ "Thu, 09 Sep 1999 09:49:04 -0400" ] , "Received" => [ q/ from mailhub ([111.11.111.111]) by mailhost.bigco.com (Netscape Messaging Server 3.6) with ESMTP id AAA527D for ; Fri, 18 Jun 1999 16:29:07 +0000 /, q/ from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473) id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com (ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT) /, q/ from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473) with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri, 18 Jun 1999 16:29:05 +0000 (GMT) /] , "Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] , "To" => [ "Big Shot ] , } ; The text in the example for the "Received" array has been formated to make reading the example easier. The actual values returned are just strings of words separated by spaces and with newlines and carriage returns stripped off. The *Received* header is probably the main reason that the *parse_headers* method creates a hash of lists rather than a hash of values. If the second argument to *parse_headers* is 'ALL' or if it is unspecified then all available headers are included in the returned hash of lists. If you're not emotionally prepared to deal with a hash of lists then you can always call the fetch method yourself with the appropriate parameters and parse the data out any way you want to. If the *Uid* parameter is true then the first argument will be treated as a message UID. If the first argument is a reference to an array of message sequence numbers (or UID's if Uid is true), then *parse_headers* will be run against each message in the array. In this case the return value is a hash, in which the key is the message sequence number (or UID) and the value is a reference to a hash as described above. An example of using *parse_headers* to print the date and subject of every message in your smut folder could look like this: use Mail::IMAPClient; my $imap = Mail::IMAPClient->new( Server => $imaphost, User => $login, Password=> $pass, Uid => 1, # optional ); $imap->select("smut"); for my $h ( # grab the Subject and Date from every message in my (fictional!) smut folder; # the first argument is a reference to an array listing all messages in the folder # (which is what gets returned by the $imap->search("ALL") method when called in # scalar context) and the remaining arguments are the fields to parse out # The key is the message number, which in this case we don't care about: values %{$imap->parse_headers( scalar($imap->search("ALL")) , "Subject", "Date")} ) { # $h is the value of each element in the hash ref returned from parse_headers, # and $h is also a reference to a hash. # We'll only print the first occurance of each field because we don't expect more # than one Date: or Subject: line per message. print map { "$_:\t$h->{$_}[0]\n"} keys %$h ; } recent() The recent method performs an IMAP SEARCH RECENT search against the selected folder and returns an array of sequence numbers (or UID's, if the *Uid* parameter is true) of messages that are recent. recent_count() The *recent_count* method accepts as an argument a folder name. It returns the number of recent messages in the folder (as returned by the IMAP client command "STATUS folder RECENT"), or undef in the case of an error. The *recent_count* method was contributed by Rob Deker (deker@ikimbo.com). rename() The rename method accepts two arguments: the name of an existing folder, and a new name for the folder. The existing folder will be renamed to the new name using the RENAME IMAP client command. rename will return a true value if successful, or undef if unsuccessful. restore_message() The *restore_message* method is used to undo a previous *delete_message* operation (but not if there has been an intervening expunge or close). The *IMAPClient* object must be in Selected status to use the *restore_message* method. The *restore_message* method accepts a list of arguments. If the *Uid* parameter is not set to a true value, then each item in the list should be either: > a message sequence number, > a comma-separated list of message sequence numbers, > a reference to an array of message sequence numbers, or If the *Uid* parameter is set to a true value, then each item in the list should be either: > a message UID, > a comma-separated list of UID's, or > a reference to an array of message UID's. The messages identified by the sequence numbers or UID's will have their *\Deleted* flags cleared, effectively "undeleting" the messages. *restore_message* returns the number of messages it was able to restore. Note that *restore_messages* is similar to calling *unset_flag("\Deleted",@msgs)*, except that *restore_messages* returns a more meaningful value. run() Like Perl itself, the *Mail::IMAPClient* module is designed to make common things easy and uncommon things possible. The run method is provided to make those uncommon things possible. The run method excepts one or two arguments. The first argument is a string containing an IMAP Client command, including a tag and all required arguments. The optional second argument is a string to look for that will indicate success. (The default is `/OK.*/'). The run method returns an array of output lines from the command, which you are free to parse as you see fit. The run method does not do any syntax checking, other than rudimentary checking for a tag. When run processes the command, it increments the transaction count and saves the command and responses in the History buffer in the same way other commands do. However, it also creates a special entry in the History buffer named after the tag supplied in the string passed as the first argument. If you supply a numeric value as the tag then you may risk overwriting a previous transaction's entry in the History buffer. If you want the control of run but you don't want to worry about the damn tags then see `"tag_and_run"' in this node, below. search() The search method implements the SEARCH IMAP client command. Any argument supplied to search is prefixed with a space and appended to the SEARCH IMAP client command. This method is another one of those situations where it will really help to have your copy of RFC2060 handy, since the SEARCH IMAP client command contains a plethora of options and possible arguments. Remember that if your argument needs quotes around it then you must make sure that the quotes will be preserved when passing the argument. I.e. use `qq/"$arg"/' instead of `"$arg"'. The search method returns an array containing sequence numbers of messages that passed the SEARCH IMAP client command's search criteria. If the *Uid* parameter is true then the array will contain message UID's. If search is called in scalar context then a pointer to the array will be passed, instead of the array itself. see() The see method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then sets the "\Seen" flag for those message(s). Of course, if the *Uid* parameter is set to a true value then those message sequence numbers had better be unique message id's, but then you already knew that, didn't you? Note that specifying `$imap-'see(@msgs)> is just a shortcut for specifying `$imap-'set_flag("Seen",@msgs)>. seen() The seen method performs an IMAP SEARCH SEEN search against the selected folder and returns an array of sequence numbers of messages that have already been seen (ie their SEEN flag is set). If the *Uid* parameter is true then an array of message UID's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned. select() The select method selects a folder and changes the object's state to "Selected". It accepts one argument, which is the name of the folder to select. sentbefore() The *sentbefore* works just like `"sentsince"' in this node, below, except it searches for messages that were sent before the date supplied as an argument to the method. senton() The *senton* works just like `"sentsince"' in this node, below, except it searches for messages that were sent on the exact date supplied as an argument to the method. sentsince() The *sentsince* method accepts one argument, a date in either standard perl format (seconds since 1/1/1970, or as output by `time|perlfunc' in this node and as accepted by `localtime|perlfunc' in this node) or in the *date_text* format as defined in RFC2060 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). It searches for items in the currently selected folder for messages sent since the day whose date is provided as the argument. It uses the RFC822 *Date:* header to determine the *sentsince* date. In the case of arguments supplied as a number of seconds, the returned result list will include items sent on or after that day, regardless of whether they arrived before the specified time on that day. The IMAP protocol does not support searches at a granularity finer than a day, so neither do I. On the other hand, the only thing I check for in a *date_text* argument is that it matches the pattern `/\d\d-\D\D\D-\d\d\d\d/' (notice the lack of anchors), so if your server lets you add something extra to a *date_text* string then so will *Mail::IMAPClient*. separator() The separator method returns the character used as a separator character in folder hierarchies. On unix-based servers, this is often a forward slash (/). It accepts one argument, the name of a folder whose hierarchy's separator should be returned. If no folder name is supplied then the separator for the INBOX is returned, which probably is good enough. set_flag() The *set_flag* method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then sets the flag specified for those message(s). Of course, if the *Uid* parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect. Note that when specifying the flag in question, the preceding backslash (\) is entirely optional. (For you, that is. *Mail::IMAPClient* still has remember to stick it in there before passing the command to the server. This is in fact so important that the method checks its argument and adds the backslash when necessary, which is why you don't have to worry about it overly much.) setacl() The *setacl* method accepts three input arguments, a folder name, a user id (or authentication identifier, to use the terminology of RFC2086), and an access rights modification string. See RFC2086 for more information. (This is somewhat experimental and its implementation may change.) since() The *since* method accepts a date in either standard perl format (seconds since 1/1/1970, or as output by `time', *Note Perlfunc: (perl.info)perlfunc, and as accepted by `localtime', *Note Perlfunc: (perl.info)perlfunc,) or in the *date_text* format as defined in RFC2060 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). It searches for items in the currently selected folder for messages whose internal dates are on or after the day whose date is provided as the argument. It uses the internal system date for a message to determine if that message was sent since the given date. In the case of arguments supplied as a number of seconds, the returned result list will include items whose internal date is on or after that day, regardless of whether they arrived before the specified time on that day. size() The size method accepts one input argument, a sequence number (or message UID if the *Uid* parameter is true). It returns the size of the message in the currently selected folder with the supplied sequence number (or UID). The *IMAPClient* object must be in a Selected state in order to use this method. status() The status method accepts one argument, the name of a folder (or mailbox, to use RFC2060's terminology), and returns an array containing the results of running the IMAP STATUS client command against that folder. If additional arguments are supplied then they are appended to the IMAP STATUS client command string, separated from the rest of the string and each other with spaces. If status is not called in an array context then it returns a reference to an array rather than the array itself. The status method should not be confused with the Status method (with an uppercase 'S'), which returns information about the *IMAPClient* object. (See the section labeled `"Status Methods"' in this node, below). subscribed() The *subscribed* method works like the *folders* method, above, except that the returned list (or array reference, if called in scalar context) contains only the subscribed folders. tag_and_run() The *tag_and_run* method accepts one or two arguments. The first argument is a string containing an IMAP Client command, without a tag but with all required arguments. The optional second argument is a string to look for that will indicate success (without pattern delimiters). The default is `OK.*'. The *tag_and_run* method will prefix your string (from the first argument) with the next transaction number and run the command. It returns an array of output lines from the command, which you are free to parse as you see fit. Using this method instead of run (above) will free you from having to worry about handling the tags (and from worrying about the side affects of naming your own tags). uidnext() The uidnext method accepts one argument, the name of a folder, and returns the numeric string that is the next available message UID for that folder. uidvalidity() The uidvalidity method accepts one argument, the name of a folder, and returns the numeric string that is the unique identifier validity value for the folder. unseen() The *unseen* method performs an IMAP SEARCH UNSEEN search against the selected folder and returns an array of sequence numbers of messages that have not yet been seen (ie their SEEN flag is not set). If the *Uid* parameter is true then an array of message UID's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned. Note that when specifying the flag in question, the preceding backslash (\) is entirely optional. unseen_count() The *unseen_count* method accepts the name of a folder as an argument and returns the number of unseen messages in that folder. If no folder argument is provided then it returns the number of unseen messages in the currently selected Folder. unset_flag() The *unset_flag* method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then unsets the flag specified for those message(s). Of course, if the *Uid* parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect. Other IMAP Client Commands and the Default Method() IMAP Client Commands not otherwise documented have been implemented via an AUTOLOAD hack and use a default method. If a program calls a method that is not defined (or inherited) by the *IMAPClient* module then the *IMAPClient* module will assume that it is an IMAP client command. It will prefix the command with the next available transaction number (or tag value), and append to it the space-delimited list of arguments supplied to the unimplemented method (if any). It will then read lines of output from the imap session until it finds a line containing the strings "OK" and "Completed", and return an array containing all of the lines of output (or, if called in scalar context, an array reference). If it finds "BAD" or "NO" instead of "OK" it returns undef. Eg: $imap->FOO("bar","an example","of the default"); results in: "99 FOO bar an example of the default\r\n" being sent to the IMAP server (assuming that 99 is the current transaction number). Notice that we used an uppercase method name "FOO" so as not to conflict with future implementations of that IMAP command. If you run your script with warnings turned on (always a good idea, at least during testing), then you will receive warnings whenever you use a lowercase method name that has not been implemented. An exception to this is when you use certain common (yet unimplemented) methods that, if ever explicitly implemented, are guaranteed to behave just like the default method. To date, these are: store("$msg[,$msg2,$msg_n]", $flags) Invoke the STORE IMAP Client command to update a message's status on the server. copy($msg,$folder) Copy a message into a folder. subscribe($folder) Subscribe to a folder create($folder) Create a new folder. delete($folder) Delete a folder (and its contents). expunge Remove messages previously marked as deleted. (This is also documented under `"object methods"' in this node, above.) *CAUTION:* Once again, remember to quote your quotes if you want quotes to be part of the IMAP command string. You can also use the default method to override the behavior of implemented IMAP methods by changing the case of the method name, preferably to all-uppercase so as not to conflict with the Class method and accessor method namespace. For example, if you don't want the search method's behavior (which returns a list of message numbers) but would rather have an array of raw data returned from your search operation, you can issue the following snippet: @raw = $imap->SEARCH("SUBJECT","Whatever..."); which is slightly more efficient than the equivalent: my @msgs = $imap->search("SUBJECT","Whatever..."); my @raw = $imap->Results; Status Methods There are several object methods that return the status of the object. They can be used at any time to check the status of an *IMAPClient* object, but are particularly useful for determining the cause of failure when a connection and login are attempted as part of a single new method invocation. The status methods are: 1. History The History method is almost identical to the *Results* method. Unlike the *Results* method, however, the IMAP command that was issued to create the results being returned is not included in the returned results. If called in a scalar context, History returns an array reference rather than an array. 2. IsUnconnected returns a true value if the object is currently in an *Unconnected* state. 3. IsConnected returns a true value if the object is currently in either a *Connected, Authenticated*, or Selected state. 4. IsAuthenticated returns a true value if the object is currently in either an Authenticated or Selected state. 5. IsSelected returns a true value if the object is currently in a Selected state. 6. LastError Internally *LastError* is implemented just like a parameter (as described in `"Parameters"' in this node, above). There is a *LastError* attribute and an eponymous accessor method which returns the *LastError* text string describing the last error condition encountered by the server. Note that some errors are more serious than others, so *LastError*'s value is only meaningful if you encounter an error condition that you don't like. For example, if you use the exists method to see if a folder exists and the folder does not exist, then an error message will be recorded in LastError even though this is not a particularly serious error. On the other hand, if you didn't use exists and just tried to select a non-existing folder, then select would return undef after setting *LastError* to something like "NO SELECT failed: Can't open mailbox : no such mailbox". At this point it would be useful to print out the contents of *LastError* as you die. 7. LastIMAPCommand New in version 2.0.4, *LastIMAPCommand* returns the exact IMAP command string to be sent to the server. Useful mainly in constructing error messages when *LastError* just isn't enough. 8. Report The *Report* method returns an array containing a history of the IMAP session up to the point that *Report* was called. It is primarily meant to assist in debugging but can also be used to retrieve raw output for manual parsing. The value of the Clear parameter controls how many transactions are in the report. (See the discussion of Clear in `"parameters"' in this node, above.) 9. Results The *Results* method returns an array containing the results of one IMAP client command. It accepts one argument, the transaction number of the command whose results are to be returned. If transaction number is unspecified then *Results* returns the results of the last IMAP client command issued. If called in a scalar context, *Results* returns an array reference rather than an array. 10. State The State method returns a numerical value that indicates the current status of the *IMAPClient* object. If invoked with an argument, it will set the object's state to that value. If invoked without an argument, it behaves just like Status, below. Normally you will not have to invoke this function. An exception is if you are bypassing the *Mail::IMAPClient* module's connect and/or login modules to set up your own connection (say, for example, over a secure socket), in which case you must manually do what the connect and login methods would otherwise do for you. 11. Status The Status method returns a numerical value that indicates the current status of the *IMAPClient* object. (Not to be confused with the status method, all lower-case, which is the implementation of the STATUS IMAP client command.) 12. Transaction The Transaction method returns the tag value (or transaction number) of the last IMAP client command. REPORTING BUGS ============== Please feel free to e-mail the author at the below address if you encounter any strange behaviors. When reporting a bug, please be sure to include the following: - As much information about your environment as possible. I especially need to know which version of Mail::IMAPClient you are running and the type/version of IMAP server to which you are connecting. - As detailed a description of the problem as possible. (What are you doing? What happens?) - An example script that demonstrates the problem (preferably with as few lines of code as possible!) and which calls the Mail::IMAPClient's new method with the Debug parameter set to "1". - Output from the example script when it's running with the Debug parameter turned on. You can edit the output to remove (or preferably to "X" out) sensitive data, such as hostnames, user names, and passwords, but PLEASE do not remove the text that identifies the TYPE of IMAP server to which you are connecting. Note that in the latest versions of Mail::IMAPClient, debugging does not print out the user or password from the login command line. However, if you use some other means of authenticating then you may need to edit the debugging output with an eye to security. - Don't be surprised if I come back asking for a trace of the problem. To provide this, you should create a file called *.perldb* in your current working directory and include the following line of text in that file: `&parse_options("NonStop=1 LineInfo=mail_imapclient_db.out");' For your debugging convenience, a sample .perldb file, which was randomly assigned the name `sample.perldb', is provided in the distribution. Next, without changing your working directory, debug the example script like this: `perl -d example_script.pl [ args ]' Note that in these examples, the script that demonstrates your problem is named "example_script.pl" and the trace output will be saved in "mail_imapclient_db.out". You should change these to suite your needs. AUTHOR ====== David J. Kernen The Kernen Consulting Group, Inc david.kernen@erols.com COPYRIGHT ========= Copyright 1999, 2000 The Kernen Group, Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the "Artistic License" which comes with this Kit, or b) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.