new(%args) # constructor

    my $imap = Net::IMAP::Client->new(%args);

Pass to the constructor a hash of arguments that can contain:

- server (STRING)

Host name or IP of the IMAP server.

- user (STRING)

User ID (only "clear" login is supported for now!)

- pass (STRING)

Password

- ssl (BOOL, optional, default FALSE)

Pass a true value if you want to use IO::Socket::SSL

- ssl_verify_peer (BOOL, optional, default TRUE)

Pass a false value if you do not want to use SSL CA to verify server

only need when you set ssl to true

- ssl_ca_file (STRING, optional)

Pass a file path which used as CA file to verify server

at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify server

-ssl_ca_path (STRING, optional)

Pass a dir which will be used as CA file search dir, found CA file will be used to verify server

On linux, by default is '/etc/ssl/certs/'

at least one of ssl_ca_file and ssl_ca_path is needed for ssl verify server

- ssl_options (HASHREF, optional)

Optional arguments to be passed to the IO::Socket::SSL object.

- uid_mode (BOOL, optional, default TRUE)

Whether to use UID command (see RFC3501). Recommended.

- socket (IO::Handle, optional)

If you already have a socket connected to the IMAP server, you can pass it here.

The ssl_ca_file and ssl_ca_path only need when you set ssl_verify_peer to TRUE.

If you havn't apply an ssl_ca_file and ssl_ca_path, on linux, the ssl_ca_path will use the value '/etc/ssl/certs/', on other platform ssl_verify_peer will be disabled.

The constructor doesn't login to the IMAP server -- you need to call $imap->login for that.

last_error

login($user, $pass)

Returns undef if login failed.

logout / quit

noop

This method fetches any notifications that the server might have for us and you can get them by calling $imap->notifications. See the "notifications()" method.

capability() / capability(qr/^SOMETHING/)

    if ($imap->capability(/^sort$/i)) {
        # speaks it
    }

This data is cached, the server will be only hit once.

select($folder)

- messages

Total number of messages in this folder

- flags

Flags available for this folder (as array ref)

- recent

Total number of recent messages in this folder

- sflags

Various other flags here, such as PERMANENTFLAGS of UIDVALIDITY. You might want to take a look at RFC3501 at this point. :-p

This method is basically stolen from Net::IMAP::Simple.

examine($folder)

status($folder), status(\@folders)

If passed an array ref, the return value is a hash ref mapping folder name to folder status (which are hash references in turn). If passed a single folder name, it returns the status of that folder only.

    my $inbox = $imap->status('INBOX');
    print $inbox->{UNSEEN}, $inbox->{MESSAGES};
    print Data::Dumper::Dumper($inbox);

    my $all = $imap->status($imap->folders);
    while (my ($name, $status) = each %$all) {
        print "$name : $status->{MESSAGES}/$status->{UNSEEN}\n";
    }

This method is designed to be very fast when passed multiple folders. It's a lot faster to call:

    $imap->status(\@folders);

than:

    $imap->status($_) foreach (@folders);

because it sends all the STATUS requests to the IMAP server before it starts receiving the answers. In my tests with my remote IMAP server, for 40 folders this method takes 0.6 seconds, compared to 6+ seconds when called individually for each folder alone.

separator

    FETCH "" "*"

I don't know of any way to change this value on a server so I have to assume it's a constant. Therefore, this method caches the result and it won't hit the server a second time on subsequent calls.

folders

    my @a = $imap->folders;
    my $b = $imap->folders;
    # now @a == @$b;

folders_more

  - flags -- folder flags (array ref; i.e. [ '\\HasChildren' ])
  - sep   -- one character containing folder hierarchy separator
  - name  -- folder name (same as the key -- thus redundant)

namespace

 - `personal' -- the personal namespace
 - `other' -- "other users" namespace
 - `shared' -- shared namespace

Each one can be undef if the server returned "NIL", or an array reference. If an array reference, each element is in the form:

 {
    sep    => '.',
    prefix => 'INBOX.'
 }

(sep is the separator for this hierarchy, and prefix is the prefix).

seq_to_uid(@sequence_ids)

On success it returns an hash reference which maps sequence numbers to message UID-s. Of course, on failure it returns undef.

search($criteria, $sort, $charset)

Note that if you use $sort and the IMAP server doesn't have this capability, this method will fail. Use "capability" to investigate.

- $criteria

Can be a string, in which case it is passed literally to the IMAP command (which can be "SEARCH" or "SORT").

It can also be an hash reference, in which case keys => values are collected into a string and values are properly quoted, i.e.:

   { subject => 'foo',
     from    => 'bar' }
    

will translate to:

   'SUBJECT "foo" FROM "bar"'
    

which is a valid IMAP SEARCH query.

If you want to retrieve all messages (no search criteria) then pass 'ALL' here.

- $sort

Can be a string or an array reference. If it's an array, it will simply be joined with a space, so for instance passing the following is equivalent:

    'SUBJECT DATE'
    [ 'SUBJECT', 'DATE' ]
    

The SORT command in IMAP allows you to prefix a sort criteria with 'REVERSE' which would mean descending sorting; this module will allow you to prefix it with '^', so again, here are some equivalent constructs:

    'SUBJECT REVERSE DATE'
    'SUBJECT ^DATE'
    [ 'SUBJECT', 'REVERSE', 'DATE' ]
    [ 'subject', 'reverse date' ]
    [ 'SUBJECT', '^DATE' ]
    

It'll also uppercase whatever you passed here.

If you omit $sort (or pass undef) then this method will use the SEARCH command. Otherwise it uses the SORT command.

- $charset

The IMAP SORT recommendation [2] requires a charset declaration for SORT, but not for SEARCH. Interesting, huh?

Our module is a bit more paranoid and it will actually add charset for both SORT and SEARCH. If $charset is omitted (or undef) the it will default to "UTF-8", which, supposedly, is supported by all IMAP servers.

get_rfc822_body($msg_id)

Note that the actual data is returned as a reference to a scalar, to speed things up.

Examples:

    my $data = $imap->get_rfc822_body(10);
    print $$data;   # need to dereference it

    my @more = $imap->get_rfc822_body([ 11, 12, 13 ]);
    print $$_ foreach @more;

        or

    my $more = $imap->get_rfc822_body([ 11, 12, 13 ]);
    print $$_ foreach @$more;

get_part_body($msg_id, $part_id)

Scalar reference

Note that again, this data is returned as a reference to a scalar rather than the scalar itself. This decision was taken purely to save some time passing around potentially large data from Perl subroutines.

Undecoded

One other thing to note is that the data is not decoded. One simple way to decode it is use Email::MIME::Encodings, i.e.:

    use Email::MIME::Encodings;
    my $summary = $imap->get_summaries(10)->[0];
    my $part = $summary->get_subpart('1.1');
    my $body = $imap->get_part_body('1.1');
    my $cte = $part->transfer_encoding;  # Content-Transfer-Encoding
    $body = Email::MIME::Encodings::decode($cte, $$body);

    # and now you should have the undecoded (perhaps binary) data.

See get_summaries below.

get_parts_bodies($msg_id, \@part_ids)

    my $parts = $imap->get_parts_bodies(10, [ '1.1', '1.2', '2.1' ]);
    print ${$parts->{'1.1'}};

get_summaries($msg, $headers) / get_summaries(\@msgs, $headers)

Fetches, parses and returns "message summaries". $msg can be an array ref, or a single id. The return value is always an array reference, even if a single message is queried.

If $headers is passed, it must be a string containing name(s) of the header fields to fetch (space separated). Example:

    $imap->get_summaries([1, 2, 3], 'References X-Original-To')

The result contains Net::IMAP::Client::MsgSummary objects. The best way to understand the result is to actually call this function and use Data::Dumper to see its structure.

Following is the output for a pretty complicated message, which contains an HTML part with an embedded image and an attached message. The attached message in turn contains an HTML part and an embedded message.

  bless( {
    'message_id' => '<48A71D17.1000109@foobar.com>',
    'date' => 'Sat, 16 Aug 2008 21:31:51 +0300',
    'to' => [
        bless( {
            'at_domain_list' => undef,
            'name' => undef,
            'mailbox' => 'kwlookup',
            'host' => 'foobar.com'
        }, 'Net::IMAP::Client::MsgAddress' )
    ],
    'cc' => undef,
    'from' => [
        bless( {
            'at_domain_list' => undef,
            'name' => 'Mihai Bazon',
            'mailbox' => 'justme',
            'host' => 'foobar.com'
        }, 'Net::IMAP::Client::MsgAddress' )
    ],
    'flags' => [
        '\\Seen',
        'NonJunk',
        'foo_bara'
    ],
    'uid' => '11',
    'subject' => 'test with message attachment',
    'rfc822_size' => '12550',
    'in_reply_to' => undef,
    'bcc' => undef,
    'internaldate' => '16-Aug-2008 21:29:23 +0300',
    'reply_to' => [
        bless( {
            'at_domain_list' => undef,
            'name' => 'Mihai Bazon',
            'mailbox' => 'justme',
            'host' => 'foobar.com'
        }, 'Net::IMAP::Client::MsgAddress' )
    ],
    'sender' => [
        bless( {
            'at_domain_list' => undef,
            'name' => 'Mihai Bazon',
            'mailbox' => 'justme',
            'host' => 'foobar.com'
        }, 'Net::IMAP::Client::MsgAddress' )
    ],
    'parts' => [
        bless( {
            'part_id' => '1',
            'parts' => [
                bless( {
                    'parameters' => {
                        'charset' => 'UTF-8'
                    },
                    'subtype' => 'html',
                    'part_id' => '1.1',
                    'encoded_size' => '365',
                    'cid' => undef,
                    'type' => 'text',
                    'description' => undef,
                    'transfer_encoding' => '7bit'
                }, 'Net::IMAP::Client::MsgSummary' ),
                bless( {
                    'disposition' => {
                        'inline' => {
                            'filename' => 'someimage.png'
                        }
                    },
                    'language' => undef,
                    'encoded_size' => '4168',
                    'description' => undef,
                    'transfer_encoding' => 'base64',
                    'parameters' => {
                        'name' => 'someimage.png'
                    },
                    'subtype' => 'png',
                    'part_id' => '1.2',
                    'type' => 'image',
                    'cid' => '<part1.02030404.05090202@foobar.com>',
                    'md5' => undef
                }, 'Net::IMAP::Client::MsgSummary' )
            ],
            'multipart_type' => 'related'
        }, 'Net::IMAP::Client::MsgSummary' ),
        bless( {
            'message_id' => '<48A530CE.3050807@foobar.com>',
            'date' => 'Fri, 15 Aug 2008 10:31:26 +0300',
            'encoded_size' => '6283',
            'to' => [
                bless( {
                    'at_domain_list' => undef,
                    'name' => undef,
                    'mailbox' => 'kwlookup',
                    'host' => 'foobar.com'
                }, 'Net::IMAP::Client::MsgAddress' )
            ],
            'subtype' => 'rfc822',
            'cc' => undef,
            'from' => [
                bless( {
                    'at_domain_list' => undef,
                    'name' => 'Mihai Bazon',
                    'mailbox' => 'justme',
                    'host' => 'foobar.com'
                }, 'Net::IMAP::Client::MsgAddress' )
            ],
            'subject' => 'Test with images',
            'in_reply_to' => undef,
            'description' => undef,
            'transfer_encoding' => '7bit',
            'parameters' => {
                'name' => 'Attached Message'
            },
            'bcc' => undef,
            'part_id' => '2',
            'sender' => [
                bless( {
                    'at_domain_list' => undef,
                    'name' => 'Mihai Bazon',
                    'mailbox' => 'justme',
                    'host' => 'foobar.com'
                }, 'Net::IMAP::Client::MsgAddress' )
            ],
            'reply_to' => [
                bless( {
                    'at_domain_list' => undef,
                    'name' => 'Mihai Bazon',
                    'mailbox' => 'justme',
                    'host' => 'foobar.com'
                }, 'Net::IMAP::Client::MsgAddress' )
            ],
            'parts' => [
                bless( {
                    'parameters' => {
                        'charset' => 'UTF-8'
                    },
                    'subtype' => 'html',
                    'part_id' => '2.1',
                    'encoded_size' => '344',
                    'cid' => undef,
                    'type' => 'text',
                    'description' => undef,
                    'transfer_encoding' => '7bit'
                }, 'Net::IMAP::Client::MsgSummary' ),
                bless( {
                    'disposition' => {
                        'inline' => {
                            'filename' => 'logo.png'
                        }
                    },
                    'language' => undef,
                    'encoded_size' => '4578',
                    'description' => undef,
                    'transfer_encoding' => 'base64',
                    'parameters' => {
                        'name' => 'logo.png'
                    },
                    'subtype' => 'png',
                    'part_id' => '2.2',
                    'type' => 'image',
                    'cid' => '<part1.02060209.09080406@foobar.com>',
                    'md5' => undef
                }, 'Net::IMAP::Client::MsgSummary' )
            ],
            'cid' => undef,
            'type' => 'message',
            'multipart_type' => 'related'
        }, 'Net::IMAP::Client::MsgSummary' )
    ],
    'multipart_type' => 'mixed'
  }, 'Net::IMAP::Client::MsgSummary' );

As you can see, the parser retrieves all data, including from the embedded messages.

There are many other modules you can use to fetch such information. Email::Simple and Email::MIME are great. The only problem is that you have to have fetched already the full (RFC822) body of the message, which is impractical over IMAP. When you want to quickly display a folder summary, the only practical way is to issue a FETCH command and retrieve only those headers that you are interested in (instead of full body). "get_summaries" does exactly that (issues a FETCH (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE BODYSTRUCTURE)). It's acceptably fast even for huge folders.

fetch($msg_id, $attributes)

$msg_id can be a single message ID or an array of IDs. If a single ID is given, the return value will be a hash reference containing the requested values. If $msg_id is an array, even if it contains a single it, then the return value will be an array of hashes.

$attributes is a string of attributes to FETCH, separated with a space, or an array (ref) of attributes.

Examples:

# retrieve the UID of the most recent message

    my $last_uid = $imap->fetch('*', 'UID')->{UID};

# fetch the flags of the first message

    my $flags = $imap->fetch(1, 'FLAGS')->{FLAGS};

# fetch flags and some headers (Subject and From)

    my $headers = 'BODY[HEADER.FIELDS (Subject From)]';
    my $results = $imap->fetch([1, 2, 3], "FLAGS $headers");
    foreach my $hash (@$results) {
        print join(" ", @{$hash->{FLAGS}}), "\n";
        print $hash->{$headers}, "\n";
    }

notifications()

Each element in this array (notification) is a hash reference containing one or more or the following:

  - seq       : the *sequence number* of the changed message
  - uid       : UID of the changed message (NOT ALWAYS available!)
  - flags     : new flags for this message
  - deleted   : when the \Deleted flag was set for this message
  - messages  : new number of messages in this folder
  - recent    : number of recent messages in this folder
  - flags     : new flags of this folder (seq is missing)
  - destroyed : when this message was expunged
  - folder    : the name of the selected folder

"folder" is always present. "seq" is present when a message was changed some flags (in which case you have "flags") or was expunged (in which case "destroyed" is true). When "flags" were changed and the \Deleted flag is present, you also get "deleted" true.

"seq" is a message sequence number. Pretty dumb, I think it's preferable to work with UID-s, but that's what the IMAP server reports. In some cases the UID might be readily available (i.e. my IMAP server sends notifications in the same body as a response to, say, a FETCH BODY command), but when it's not, you have to rely on seq_to_uid(). Note that when "destroyed" is true, the message has been expunged; there is no way in this case to retrieve the UID so you have to rely solely on "seq" in order to update your caches.

When "flags" is present but no "seq", it means that the list of available flags for the "folder" has changed.

You get "messages" upon an "EXISTS" notification, which usually means "you have new mail". It indicates the total number of messages in the folder, not just "new" messages. I've yet to come up with a good way to measure the number of new/unseen messages, other than calling "status($folder)".

I rarely got "recent" from my IMAP server in my tests; if more clients are simultaneously logged in as the same IMAP user, only one of them will receive "RECENT" notifications; others will have to rely on "EXISTS" to tell when new messages have arrived. Therefore I can only say that "RECENT" is useless and I advise you to ignore it.

append($folder, \$rfc822, $flags, $date)

$date specifies the INTERNALDATE of the appended messge. If undef it will default to the current date/time. NOTE: this functionality is not tested; $date should be in a format understood by IMAP.

get_flags($msg_id) / get_flags(\@msg_ids)

When an array was passed, the returned hash will map each message UID to an array of flags.

store($msg, $flag) / store(\@msgs, \@flags)

Note that the folder where these messages reside must have been already selected.

Examples:

    $imap->store(10, '\\Seen');
    $imap->store([11, 12], '\\Deleted');
    $imap->store(13, [ '\\Seen', '\\Answered' ]);

The IMAP specification defines certain reserved flags (they all start with a backslash). For example, a message with the flag "\Deleted" should be regarded as deleted and will be permanently discarded by an EXPUNGE command. Although, it is possible to "undelete" a message by removing this flag.

The following reserved flags are defined by the IMAP spec:

    \Seen
    \Answered
    \Flagged
    \Deleted
    \Draft
    \Recent

The "\Recent" flag is considered "read-only" -- you cannot add or remove it manually; the server itself will do this as appropriate.

add_flags($msg, $flag) / add_flags(\@msgs, \@flags)

del_flags($msg, $flag) / del_flags(\@msgs, \@flags)

delete_message($msg) / delete_message(\@msgs)

    $imap->add_flags(\@msgs, '\\Deleted');

expunge()

copy($msg, $folder) / copy(\@msg_ids, $folder)

create_folder($folder)

delete_folder($folder)

Note that all messages in $folder, as well as in any subfolders, are permanently lost.

get_threads($algorithm, $msg_id)

$algorithm should be undef, "REFERENCES" or "SUBJECT". If undefined, "REFERENCES" is assumed. This selects the threading algorithm, as per IMAP THREAD AND SORT extensions specification. I only tested "REFERENCES".

$msg_id can be undefined, or a message ID. If it's undefined, then a threaded view of the whole folder will be returned. If you pass a message ID, then this method will return the top-level thread that contains the message.

The return value is an array which actually represents threads. Elements of this array are message ID-s, or other arrays (which in turn contain message ID-s or other arrays, etc.). The first element in an array will represent the start of the thread. Subsequent elements are child messages or subthreads.

An example should help (FIXME).