.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::IMAP::SimpleX 3" .TH Net::IMAP::SimpleX 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Net::IMAP::SimpleX \- Addons for Net::IMAP::Simple .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 3 \& use strict; \& use warnings; \& use Net::IMAP::SimpleX; .Ve .PP Net::IMAP::SimpleX uses Net::IMAP::Simple as a base so the object creation is the same as it is for the ancestor: .PP .Vb 2 \& my $imap = Net::IMAP::SimpleX\->new(\*(Aqimap.example.com\*(Aq) || \& die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\en"; \& \& $imap\->select("INBOX"); .Ve .PP Net::IMAP::SimpleX is a collection of handy methods that are not simple, require Parse::RecDescent, or are experimental. .SH DESCRIPTION .IX Header "DESCRIPTION" This module adds some useful, yet not so simple, extensions on top of Net::IMAP::Simple. .SH METHODS .IX Header "METHODS" .IP new 4 .IX Item "new" For details on the invocation, read Net::IMAP::Simple. .IP body_summary 4 .IX Item "body_summary" Typical invocations will take this overall shape. .Sp .Vb 2 \& # 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/ \& } .Ve .Sp 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 \fIfetch body\fR command. The parser uses the formal syntax as defined by RFC3501 . .Sp .Vb 11 \& my $body = $summary\->body; \& my @attr = map { $body\->$_ } qw/ \& content_description \& encoded_size \& charset \& content_type \& part_number \& format \& id \& encoding \& /; .Ve .Sp For multipart messages, the object contains sub-objects for each message part, accessible via the \fBparts()\fR method and inspected via the \fBhas_parts()\fR 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. .Sp An example of a multipart, alternative message with a text body and an html version of the body would looke something like: .Sp .Vb 5 \& if ($summary\->has_parts) { \& if ($summary\->type eq \*(Aqalternative\*(Aq) { \& my ($html) = grep { $_\->content_type eq \*(Aqtext/html\*(Aq } $summary\->parts; \& } \& } .Ve .Sp A really complex, multipart message could look something like this: .Sp .Vb 1 \& if ($summary\->has_parts && $summary\->type eq \*(Aqmixed\*(Aq) { \& \& for my $part ($summary\->parts) { \& if ($part\->has_parts && $part\->type eq \*(Aqmixed\*(Aq) { ... } \& ... \& } \& \& } .Ve .IP fetch 4 .IX Item "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. .Sp .Vb 10 \& my $res =$imap\->fetch(\*(Aq30:32\*(Aq => \*(AqUID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS\*(Aq) \& # $res = { \& # 30 => { \& # "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 \-0400\er\en\er\en", \& # "FLAGS" => ["\e\eFlagged", "\e\eSeen"], \& # "UID" => 58890, \& # }, \& # 31 => { \& # "BODY[HEADER.FIELDS (DATE)]" => "Date: Wed, 21 Jul 2010 09:09:04 \-0400\er\en\er\en", \& # "FLAGS" => ["\e\eSeen"], \& # "UID" => 58891, \& # }, \& # 32 => { \& # "BODY[HEADER.FIELDS (DATE)]" => "Date: Sat, 24 Jul 2010 05:12:06 \-0700\er\en\er\en", \& # "FLAGS" => ["\e\eSeen"], \& # "UID" => 58892, \& # }, \& # } .Ve .Sp So-called "parenthized" lists will be returned as an array (see \f(CW\*(C`FLAGS\*(C'\fR) but nearly everything else will come back as strings. This includes parenthized queries. Take \f(CW\*(C`BODY.PEAK[HEADER.FIELDS (DATE FROM SUBJECT)]\*(C'\fR), for example. The result would come back as the RFC822 header lines (as the above \f(CW\*(C`Date: Sun, \&...\*(C'\fR has done). .Sp For more information about the different types of queries, see RFC3501. There's a surprising number of things that can be queried. .IP uidfetch 4 .IX Item "uidfetch" This is roughly the same thing as the \f(CWfetch()\fR method above, but the query runs on UIDs instead of sequence numbers. The keys of the \f(CW$res\fR are still the sequence numbers though. .Sp .Vb 8 \& my $res =$imap\->fetch(\*(Aq58890\*(Aq => \*(AqUID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS\*(Aq) \& # $res = { \& # 30 => { \& # "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 \-0400\er\en\er\en", \& # "FLAGS" => ["\e\eFlagged", "\e\eSeen"], \& # "UID" => 58890, \& # }, \& # ... .Ve .SH AUTHOR .IX Header "AUTHOR" .IP "INITIAL AUTHOR" 4 .IX Item "INITIAL AUTHOR" Jason Woodward \f(CW\*(C`\*(C'\fR .IP "ADDITIONAL CONTRIBUTIONS" 4 .IX Item "ADDITIONAL CONTRIBUTIONS" Paul Miller \f(CW\*(C`\*(C'\fR [\fR\f(BIfetch()\fR\fI\fR] .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (c) 2010 Jason Woodward .PP All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH LICENSE .IX Header "LICENSE" This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0. .PP 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. .SH BUGS .IX Header "BUGS" .SH "SEE ALSO" .IX Header "SEE ALSO" perl, Net::IMAP::Simple, Parse::RecDescent