
=head1 NAME

Mail::Box::IMAP4::Message - one message on a IMAP4 server


=head1 INHERITANCE

 Mail::Box::IMAP4::Message
   is a Mail::Box::Net::Message
   is a Mail::Box::Message
   is a Mail::Message
   is a Mail::Reporter


=head1 SYNOPSIS

 my $folder = new Mail::Box::IMAP4 ...
 my $message = $folder->message(10);


=head1 DESCRIPTION

A C<Mail::Box::IMAP4::Message> represents one message on a IMAP4 server,
maintained by a L<Mail::Box::IMAP4|Mail::Box::IMAP4> folder. Each message is stored as
separate entity on the server, and maybe temporarily in your program
as well.



=head1 METHODS


=head2 Constructors


$obj-E<gt>B<clone>

=over 4

See L<Mail::Message/"Constructors">

=back

Mail::Box::IMAP4::Message-E<gt>B<coerce>(MESSAGE)

=over 4

See L<Mail::Box::Message/"METHODS">

=back

Mail::Box::IMAP4::Message-E<gt>B<new>(OPTIONS)

=over 4

 Option      Defined in       Default                                                       
 body        L<Mail::Message>  undef                                                         
 body_type   L<Mail::Box::Message>  L<Mail::Message::Body::Lines|Mail::Message::Body::Lines>      
 deleted     L<Mail::Box::Message>  <false>                                                       
 field_type  L<Mail::Message>  undef                                                         
 folder      L<Mail::Box::Message>  <required>                                                    
 head        L<Mail::Message>  undef                                                         
 head_type   L<Mail::Message>  L<Mail::Message::Head::Complete|Mail::Message::Head::Complete>
 labels      L<Mail::Message>  {}                                                            
 log         L<Mail::Reporter>  C<'WARNINGS'>                                                 
 messageId   L<Mail::Message>  undef                                                         
 modified    L<Mail::Message>  <false>                                                       
 size        L<Mail::Box::Message>  undef                                                         
 trace       L<Mail::Reporter>  C<'WARNINGS'>                                                 
 trusted     L<Mail::Message>  <false>                                                       
 unique      L<Mail::Box::Net::Message>  <unique string>                                               

. body OBJECT

. body_type CODE|CLASS

. deleted BOOLEAN

. field_type CLASS

. folder FOLDER

. head OBJECT

. head_type CLASS

. labels ARRAY|HASH

. log LEVEL

. messageId STRING

. modified BOOLEAN

. size INTEGER

. trace LEVEL

. trusted BOOLEAN

. unique STRING

=back

=head2 Constructing a message


$obj-E<gt>B<bounce>([RG-OBJECT|OPTIONS])

=over 4

See L<Mail::Message::Construct::Bounce/"Constructing a message">

=back

Mail::Box::IMAP4::Message-E<gt>B<build>([MESSAGE|BODY], CONTENT)

=over 4

See L<Mail::Message::Construct::Build/"Constructing a message">

=back

Mail::Box::IMAP4::Message-E<gt>B<buildFromBody>(BODY, [HEAD], HEADERS)

=over 4

See L<Mail::Message::Construct::Build/"Constructing a message">

=back

$obj-E<gt>B<forward>(OPTIONS)

=over 4

See L<Mail::Message::Construct::Forward/"Constructing a message">

=back

$obj-E<gt>B<forwardPostlude>

=over 4

See L<Mail::Message::Construct::Forward/"Constructing a message">

=back

$obj-E<gt>B<forwardPrelude>

=over 4

See L<Mail::Message::Construct::Forward/"Constructing a message">

=back

$obj-E<gt>B<forwardSubject>(STRING)

=over 4

See L<Mail::Message::Construct::Forward/"Constructing a message">

=back

Mail::Box::IMAP4::Message-E<gt>B<read>(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS)

=over 4

See L<Mail::Message::Construct::Read/"Constructing a message">

=back

$obj-E<gt>B<rebuild>(OPTIONS)

=over 4

See L<Mail::Message::Construct::Rebuild/"Constructing a message">

=back

$obj-E<gt>B<reply>(OPTIONS)

=over 4

See L<Mail::Message::Construct::Reply/"Constructing a message">

=back

$obj-E<gt>B<replyPrelude>([STRING|FIELD|ADDRESS])

=over 4

See L<Mail::Message::Construct::Reply/"Constructing a message">

=back

$obj-E<gt>B<replySubject>(STRING)

Mail::Box::IMAP4::Message-E<gt>B<replySubject>(STRING)

=over 4

See L<Mail::Message::Construct::Reply/"Constructing a message">

=back

=head2 The Message


$obj-E<gt>B<container>

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<isDummy>

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<isPart>

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<messageId>

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<print>([FILEHANDLE])

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<send>([MAILER], OPTIONS)

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<size>

=over 4

Returns the size of this message.  If the message is still on the remote
server, IMAP is used to ask for the size.  When the message is already loaded
onto the local system, the size of the parsed message is taken.  These
sizes can differ because the difference in line-ending representation.

=back

$obj-E<gt>B<toplevel>

=over 4

See L<Mail::Message/"The Message">

=back

$obj-E<gt>B<write>([FILEHANDLE])

=over 4

See L<Mail::Message/"The Message">

=back

=head2 The header


$obj-E<gt>B<bcc>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<cc>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<date>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<destinations>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<from>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<get>(FIELDNAME)

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<guessTimestamp>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<head>([HEAD])

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<nrLines>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<sender>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<study>(FIELDNAME)

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<subject>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<timestamp>

=over 4

See L<Mail::Message/"The header">

=back

$obj-E<gt>B<to>

=over 4

See L<Mail::Message/"The header">

=back

=head2 The body


$obj-E<gt>B<body>([BODY])

=over 4

See L<Mail::Message/"The body">

=back

$obj-E<gt>B<decoded>(OPTIONS)

=over 4

See L<Mail::Message/"The body">

=back

$obj-E<gt>B<encode>(OPTIONS)

=over 4

See L<Mail::Message/"The body">

=back

$obj-E<gt>B<isMultipart>

=over 4

See L<Mail::Message/"The body">

=back

$obj-E<gt>B<isNested>

=over 4

See L<Mail::Message/"The body">

=back

$obj-E<gt>B<parts>(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])

=over 4

See L<Mail::Message/"The body">

=back

=head2 The message


$obj-E<gt>B<copyTo>(FOLDER)

=over 4

See L<Mail::Box::Message/"The message">

=back

$obj-E<gt>B<folder>([FOLDER])

=over 4

See L<Mail::Box::Message/"The message">

=back

$obj-E<gt>B<moveTo>(FOLDER)

=over 4

See L<Mail::Box::Message/"The message">

=back

$obj-E<gt>B<seqnr>([INTEGER])

=over 4

See L<Mail::Box::Message/"The message">

=back

$obj-E<gt>B<unique>([STRING])

=over 4

See L<Mail::Box::Net::Message/"The message">

=back

=head2 Flags


$obj-E<gt>B<delete>

=over 4

See L<Mail::Box::Message/"Flags">

=back

$obj-E<gt>B<deleted>([BOOLEAN])

=over 4

See L<Mail::Box::Message/"Flags">

=back

$obj-E<gt>B<isDeleted>

=over 4

See L<Mail::Box::Message/"Flags">

=back

$obj-E<gt>B<isModified>

=over 4

See L<Mail::Message/"Flags">

=back

$obj-E<gt>B<label>(LABEL, [VALUE, [LABEL, VALUE, ...]])

=over 4

With only one argument, the value related to LABEL is returned.  With
more that one argument, the list is interpreted a LABEL-VALUE pairs
to be set.

The IMAP protocol defines its own names for the labels, which must
be set imediately to inform other IMAP clients which may have the
same folder open.  Some labels are translated to the corresponding
IMAP system labels. 

=back

$obj-E<gt>B<labels>

=over 4

See L<Mail::Message/"Flags">

=back

$obj-E<gt>B<modified>([BOOLEAN])

=over 4

See L<Mail::Message/"Flags">

=back

=head2 The whole message as text


$obj-E<gt>B<file>

=over 4

See L<Mail::Message::Construct::Text/"The whole message as text">

=back

$obj-E<gt>B<lines>

=over 4

See L<Mail::Message::Construct::Text/"The whole message as text">

=back

$obj-E<gt>B<printStructure>([FILEHANDLE][, INDENT])

=over 4

See L<Mail::Message::Construct::Text/"The whole message as text">

=back

$obj-E<gt>B<string>

=over 4

See L<Mail::Message::Construct::Text/"The whole message as text">

=back

=head2 Internals


$obj-E<gt>B<diskDelete>

=over 4

See L<Mail::Box::Message/"Internals">

=back

$obj-E<gt>B<isDelayed>

=over 4

See L<Mail::Message/"Internals">

=back

$obj-E<gt>B<loadBody>

=over 4

See L<Mail::Box::Net::Message/"Internals">

=back

$obj-E<gt>B<readBody>(PARSER, HEAD [, BODYTYPE])

=over 4

See L<Mail::Box::Message/"Internals">

=back

$obj-E<gt>B<readFromParser>(PARSER, [BODYTYPE])

=over 4

See L<Mail::Message/"Internals">

=back

$obj-E<gt>B<readHead>(PARSER [,CLASS])

=over 4

See L<Mail::Message/"Internals">

=back

$obj-E<gt>B<recursiveRebuildPart>(PART, OPTIONS)

=over 4

See L<Mail::Message::Construct::Rebuild/"Internals">

=back

$obj-E<gt>B<storeBody>(BODY)

=over 4

See L<Mail::Message/"Internals">

=back

$obj-E<gt>B<takeMessageId>([STRING])

=over 4

See L<Mail::Message/"Internals">

=back

=head2 Error handling


$obj-E<gt>B<AUTOLOAD>

=over 4

See L<Mail::Message::Construct/"METHODS">

=back

$obj-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

Mail::Box::IMAP4::Message-E<gt>B<defaultTrace>([LEVEL, [LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<errors>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<log>([LEVEL [,STRINGS]])

Mail::Box::IMAP4::Message-E<gt>B<log>([LEVEL [,STRINGS]])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<logPriority>(LEVEL)

Mail::Box::IMAP4::Message-E<gt>B<logPriority>(LEVEL)

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<logSettings>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<notImplemented>

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<report>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<reportAll>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<shortSize>([VALUE])

Mail::Box::IMAP4::Message-E<gt>B<shortSize>([VALUE])

=over 4

See L<Mail::Message/"Error handling">

=back

$obj-E<gt>B<shortString>

=over 4

See L<Mail::Message/"Error handling">

=back

$obj-E<gt>B<trace>([LEVEL])

=over 4

See L<Mail::Reporter/"Error handling">

=back

$obj-E<gt>B<warnings>

=over 4

See L<Mail::Reporter/"Error handling">

=back

=head2 Cleanup


$obj-E<gt>B<DESTROY>

=over 4

See L<Mail::Message/"Cleanup">

=back

$obj-E<gt>B<destruct>

=over 4

See L<Mail::Box::Message/"Cleanup">

=back

$obj-E<gt>B<inGlobalDestruction>

=over 4

See L<Mail::Reporter/"Cleanup">

=back



=head1 DIAGNOSTICS

I<Error:> Cannot include forward source as $include.

Unknown alternative for the L<forward(include)|Mail::Message::Construct::Forward/"Constructing a message">.  Valid choices are
C<NO>, C<INLINE>, and C<ATTACH>.

I<Error:> Cannot include reply source as $include.

Unknown alternative for the C<include> option of L<reply()|Mail::Message::Construct::Reply/"Constructing a message">.  Valid
choices are C<NO>, C<INLINE>, and C<ATTACH>.

I<Error:> No address to create forwarded to.

If a forward message is created, a destination address must be specified.

I<Error:> No default mailer found to send message.

The message L<send()|Mail::Message/"The Message"> mechanism had not enough information to automatically
find a mail transfer agent to sent this message.  Specify a mailer
explicitly using the C<via> options.

I<Error:> Package $package does not implement $method.

Fatal error: the specific package (or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes do implement this method however the class at hand does
not.  Probably you should investigate this and probably inform the author
of the package.

I<Error:> Unable to read delayed body.


I<Error:> Unable to read delayed head.


I<Error:> no rebuild rule $name defined.



=head1 DETAILS


=head2 Labels


=head3 IMAP protocol flags

Labels (or flags) are known to all folder formats, but differ how they
are stored.  Some folder types use message header lines to keep the
labels, other use a seperate file.  The IMAP protocol does not specify
how the labels are kept, but does specify how they are named.

The label names as defined by the IMAP protocol are are standardized into
the MailBox standard to hide folder differences.  The following translations
are performed always:

 \Seen     => seen
 \Answered => replied
 \Flagged  => flagged
 \Deleted  => deleted
 \Draft    => draft
 \Recent   => NOT old

Other flags may be used as well, but will be translated into lower-case,
because IMAP servers may behave case-insensive.

I<Example:> of label translations


 $imap->message(3)->label(replied => 1, draft => 0);

will result in a IMAP protocol statements like

 A003 STORE 4 +FLAGS (\Answered)
 A003 STORE 4 -FLAGS (\Draft)





=head1 REFERENCES

See the MailBox website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Distribution version 2.046.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


