NAME¶
Net::IMAP::SimpleX - Addons for Net::IMAP::Simple
SYNOPSIS¶
use strict;
use warnings;
use Net::IMAP::SimpleX;
Net::IMAP::SimpleX uses Net::IMAP::Simple as a base so the object creation is
the same as it is for the ancestor:
my $imap = Net::IMAP::SimpleX->new('imap.example.com') ||
die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";
$imap->select("INBOX");
Net::IMAP::SimpleX is a collection of handy methods that are not simple, require
Parse::RecDescent, or are experimental.
DESCRIPTION¶
This module adds some useful, yet not so simple, extensions on top of
Net::IMAP::Simple.
METHODS¶
- new
- For details on the invocation, read Net::IMAP::Simple.
- body_summary
- Typical invocations will take this overall shape.
# get an object representation of the message body
my $summary = $imap->body_summary($message_number);
# multipart message
if ($summary->has_parts) {
for my $subpart ($summary->parts) {
if ($subpart->has_parts) { ... }
# examine the message part
my @attr = map { $subpart->$_ } qw/content_type encoding encoded_size/;
# fetch the raw message part
my $subpart_body = $imap->get($message_number, $subpart->part_number);
}
} else {
my $body = $summary->body;
my @attr = map { $body->$_ } qw/content_type encoding encoded_size/
}
This method returns a simple object that contains a representation of the
body of a message. The object is built by a Parse::RecDescent parser using
the output of an IMAP fetch body command. The parser uses the
formal syntax as defined by RFC3501
http://tools.ietf.org/html/rfc3501#section-9
<http://tools.ietf.org/html/rfc3501#section-9>.
my $body = $summary->body;
my @attr = map { $body->$_ } qw/
content_description
encoded_size
charset
content_type
part_number
format
id
encoding
/;
For multipart messages, the object contains sub-objects for each message
part, accessible via the parts() method and inspected via the
has_parts() method. The type method describes the type of multipart
(such as mixed or alternative). The parts method returns a list of sub
parts, which themselves may have subparts, and so on.
An example of a multipart, alternative message with a text body and an html
version of the body would looke something like:
if ($summary->has_parts) {
if ($summary->type eq 'alternative') {
my ($html) = grep { $_->content_type eq 'text/html' } $summary->parts;
}
}
A really complex, multipart message could look something like this:
if ($summary->has_parts && $summary->type eq 'mixed') {
for my $part ($summary->parts) {
if ($part->has_parts && $part->type eq 'mixed') { ... }
...
}
}
- fetch
- The fetch command returns the various parts of messages
that users request. It is fairly complicated (following RFC3501 using a
grammar/parser), but there are some basic patterns that it follows.
my $res =$imap->fetch('30:32' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
# $res = {
# 30 => {
# "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400\r\n\r\n",
# "FLAGS" => ["\\Flagged", "\\Seen"],
# "UID" => 58890,
# },
# 31 => {
# "BODY[HEADER.FIELDS (DATE)]" => "Date: Wed, 21 Jul 2010 09:09:04 -0400\r\n\r\n",
# "FLAGS" => ["\\Seen"],
# "UID" => 58891,
# },
# 32 => {
# "BODY[HEADER.FIELDS (DATE)]" => "Date: Sat, 24 Jul 2010 05:12:06 -0700\r\n\r\n",
# "FLAGS" => ["\\Seen"],
# "UID" => 58892,
# },
# }
So-called "parenthized" lists will be returned as an array (see
"FLAGS") but nearly everything else will come back as strings.
This includes parenthized queries. Take "BODY.PEAK[HEADER.FIELDS
(DATE FROM SUBJECT)]"), for example. The result would come back as
the RFC822 header lines (as the above "Date: Sun, ..." has
done).
For more information about the different types of queries, see RFC3501.
There's a surprising number of things that can be queried.
- uidfetch
- This is roughly the same thing as the "fetch()"
method above, but the query runs on UIDs instead of sequence numbers. The
keys of the $res are still the sequence numbers though.
my $res =$imap->fetch('58890' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
# $res = {
# 30 => {
# "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400\r\n\r\n",
# "FLAGS" => ["\\Flagged", "\\Seen"],
# "UID" => 58890,
# },
# ...
AUTHOR¶
- INITIAL AUTHOR
- Jason Woodward "<woodwardj@jaos.org>"
- ADDITIONAL CONTRIBUTIONS
- Paul Miller "<jettero@cpan.org>"
[fetch()]
COPYRIGHT¶
Copyright (c) 2010 Jason Woodward
All rights reserved. This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
LICENSE¶
This module is free software. You can redistribute it and/or modify it under the
terms of the Artistic License 2.0.
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.
BUGS¶
https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple
<
https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple>
SEE ALSO¶
perl, Net::IMAP::Simple, Parse::RecDescent