/ 
Mail-Box-2.023
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Message

NAME

Mail::Message - general message object

CLASS INHERITANCE

Mail::Message has extra code in Mail::Message::Construct

Mail::Message is a Mail::Reporter

Mail::Message is extended by Mail::Box::Message Mail::Message::Dummy Mail::Message::Part

SYNOPSIS

use Mail::Box::Manager;
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => 'InBox');
my $msg    = $folder->message(2);    # $msg is a Mail::Message now

my $subject = $msg->subject;         # The message's subject
my @cc      = $msg->cc;              # List of Mail::Address'es

my $msg       = Mail::Message->build(...);
my $reply_msg = Mail::Message->reply(...);
my $frwd_msg  = Mail::Message->forward(...);

my Mail::Message::Head $head = $msg->head;
my Mail::Message::Body $body = $msg->decoded;
$msg->decoded->print($outfile);

DESCRIPTION

A Mail::Message object is a container for MIME-encoded message information, as defined by RFC2822. Everything what is not specificly related to storing the messages in mailboxes (folders) is implemented in this class. Methods which are are related to folders is implemented in the Mail::Box::Message extension.

The main methods are get(), to get information from a message header field, and decoded() to get the intended content of a message. But there are many more which can assist your program.

Complex message handling (like construction of replies) are implemented in the Mail::Message::Construct package which is autoloaded into this class. This means you can simply use these methods as if they are part of this class. That package adds functionality to all kinds of Mail::Message objects.

Structure of a Message

A MIME-compliant message is build upon two parts: the head and the body. The body contains the payload: the data to be transfered. The data can be encoded, only accessible with a specific application, and may use some weird character-set, like Vietnamese; the Mail::Box module tries to assist you with handling these e-mails without the need to know all the detauls. This additional information (meta-information) about the body data is stored in the header.

The header is a list of fields, some spanning more than one line (folded) each telling something about the message. Information stored in here are for instance the sender of the message, the receivers of the message, when it was transported, how it was transported, etc etc. Headers can grow quite large.

Implementation

In Mail::Box, each message object manages exactly one header object (a Mail::Message::Head) and one body object (a Mail::Message::Body). See the methods in Mail::Message::Construct if you want to do complicated things.

Mail::Box is as lazy as possible. Whenever you open a folder, it tries to avoid processing the messages within that folder. In stead of parsing (decoding) the messages when the folder is opened, they are parsed the moment they are used for the first time. In Mail::Box, this is called delayed loading.

METHODS

Initiation

new OPTIONS 
OPTION               DEFAULT
body                 undef
body_type            'Mail::Message::Body::Lines'
field_type           undef
head                 undef
head_type            'Mail::Message::Head::Complete'
log                  'WARNINGS'
messageId            undef
modified             <false>
trace                'WARNINGS'
trusted              <false>
body => OBJECT

Instantiate the message with a body which has been created somewhere before the message is constructed. The OBJECT must be a sub-class of Mail::Message::Body. See also body() and storeBody().

body_type => CLASS

Default type of body to be created for readBody().

field_type => CLASS
head => OBJECT

Instantiate the message with a head which has been created somewhere before the message is constructed. The OBJECT must be a (sub-)class of Mail::Message::Head. See also head().

head_type => CLASS

Default type of head to be created for readHead().

log => LEVEL

See Mail::Reporter::new(log)

messageId => STRING

The id on which this message can be recognized. If none specified and not defined in the header --but one is needed-- there will be one assigned to the message to be able to pass unique message-ids between objects.

modified => BOOLEAN

Flags this message as being modified from the beginning on. Usually, modification is auto-detected, but there may be reasons to be extra explicit.

trace => LEVEL

See Mail::Reporter::new(trace)

trusted => BOOLEAN

Is this message from a trusted source? If not, the content must be checked before use. This checking will be performed when the body data is decoded or used for transmission.

Constructing a Message

bounce OPTIONS

See Mail::Message::Construct::bounce()

build [MESSAGE|BODY], CONTENT

See Mail::Message::Construct::build()

buildFromBody BODY, HEADERS

See Mail::Message::Construct::buildFromBody()

coerce MESSAGE

(Class method) Coerce a MESSAGE into a Mail::Message. In some occasions, for instance where you add a message to a folder, this coercion is automatically called to ensure that the correct message type is stored.

The coerced message is returned on success, otherwise undef. The coerced message may be a reblessed version of the original message or a new object. In case the message has to be specialized, for instance from a general Mail::Message into a Mail::Box::Mbox::Message, no copy is needed. However, to coerce a Mail::Internet object into a Mail::Message, a lot of copying and converting will take place.

Valid MESSAGEs which can be coerced into Mail::Message objects are of type

  • Any type of Mail::Box::Message

  • MIME::Entity's, using Mail::Message::Convert::MimeEntity

  • Mail::Internet's, using Mail::Message::Convert::MailInternet

Mail::Message::Part's, which are extensions of Mail::Message's, can also be coerced directly from a Mail::Message::Body.

Examples:

my $folder  = Mail::Box::Mbox->new;
my $message = Mail::Message->build(...);

my $coerced = Mail::Box::Mbox::Message->coerce($message);
$folder->addMessage($coerced);

Simpler replacement for the previous two lines:

my $coerced = $folder->addMessage($message);
forward OPTIONS

See Mail::Message::Construct::forward()

forwardPostlude

See Mail::Message::Construct::forwardPostlude()

forwardPrelude

See Mail::Message::Construct::forwardPrelude()

forwardSubject STRING

See Mail::Message::Construct::forwardSubject()

read FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS

See Mail::Message::Construct::read()

reply OPTIONS

See Mail::Message::Construct::reply()

replyPrelude [STRING|FIELD|ADDRESS]

See Mail::Message::Construct::replyPrelude()

replySubject STRING

See Mail::Message::Construct::replySubject()

The Message

clone

Create a copy of this message. Returned is a Mail::Message object. The head and body, the log and trace levels are taken. Labels are copied with the message, but the delete and modified flags are not.

BE WARNED: the clone of any kind of message (or a message part) will always be a Mail::Message object. For example, a Mail::Box::Message's clone is detached from the folder of its original. When you use Mail::Box::addMessage() with the cloned message at hand, then the clone will automatically be coerced into the right message type to be added.

See also copyTo() and moveTo().

Examples:

$copy = $msg->clone;
isDummy

Dummy messages are used to fill holes in linked-list and such, where only a message-id is known, but not the place of the header of body data.

This method is also available for Mail::Message::Dummy objects, where this will return true. On any extension of Mail::Message, this will return false.

isPart

Returns true if the message is a part of another message. This is the case for Mail::Message::Part extensions of Mail::Message. See parent() for examples.

messageId

Retrieve the message's id. Every message has a unique message-id. This id is used mainly for recognizing discussion threads.

modified [BOOLEAN]

Returns (optionally after setting) whether this message is flagged as being modified. The modification flag is set true when header lines are changed, the header or body replaced by a new one, or when labels are modified.

parent

If the message is a part of another message, parent returns the reference to the containing message. parent returns undef if the message is not a part, but rather the main message.

Examples:

my Mail::Message $msg = ...
return unless $msg->body->isMultipart;
my $part   = $msg->body->part(2);

return unless $part->body->isMultipart;
my $nested = $part->body->part(3);

$nested->parent;     # returns $part
$nested->toplevel;   # returns $msg
$msg->parent;        # returns undef
$msg->toplevel;      # returns $msg
$msg->isPart;        # returns false
$part->isPart;       # returns true

Print the message to the FILE-HANDLE, which defaults to the selected filehandle.

Examples:

$message->print(\*STDERR);
$message->print;

my $out = IO::File->new('out', 'w');
$message->print($out);
send [MAILER], OPTIONS

Transmit the message to anything outside this Perl program. MAILER is a Mail::Transport::Send object. When the MAILER is not specified, one will be created, and kept as default for the next messages as well. The OPTIONS are mailer specific.

$message->send;

is short (but little less flexibile) for

my $mailer = Mail::Transport::SMTP->new(@smtpopts);
$mailer->send($message, @sendopts);
size

Returns the size of the whole message in bytes.

toplevel

Returns a reference to the main message, which will be the current message if the message is not part of another message. See parent() for examples.

The Header

head [HEAD]

Return (optionally after setting) the HEAD of this message. The head must be an (sub-)class of Mail::Message::Head. When the head is added, status information is taken from it and transformed into labels. More labels can be added by the LABELS hash. They are added later.

Examples:

my $head = $msg->head(new Mail::Message::Head);

Header Shortcuts

bcc

Returns the addresses which are specified on the Bcc header line(s) A list of Mail::Address objects is returned. Bcc stands for Blind Carbon Copy: destinations of the message which are not listed in the messages actually sent. So, this field will be empty for received messages, but may be present in messages you construct yourself.

cc

Returns the addresses which are specified on the Cc header line(s) A list of Mail::Address objects is returned. Cc stands for Carbon Copy; the people addressed on this line receive the message informational, and are usually not expected to reply on its content.

date

Returns the last Date header line as string.

Examples:

my $date = $message->date;
destinations

Returns a list of Mail::Address objects which contains the combined info of active To, Cc, and Bcc addresses. Doubles are removed.

from

Returns the address(es) of the sender(s). Returned is a list of Mail::Address objects, which represent the addresses found on the From header field. Usually, this is only one address, but there can be more.

If you need exactly one address to return (for instance to reply a message to), you should use sender().

Examples:

my @from = $message->from;
get FIELD

Returns the value which is stored in the header FIELD with the specified name. If the field has multiple appearances in the header, only the last instance is returned.

The field name is case insensitive. the unfolded body of the field is returned, see Mail::Message::Field::unfolded_body(). If you need more complex handing of fields, then call Mail::Message::Head::get() yourself.

Examples:

print $msg->get('Content-Type'), "\n";

Is equivalent to:

print $msg->head->get('Content-Type')->unfolded_body, "\n";
guessTimestamp

Return an estimate on the time this message was sent. The data is derived from the header, where it can be derived from the date and received lines. For MBox-like folders you may get the date from the from-line as well.

This method may return undef if the header is not parsed or only partially known. If you require a time, then use the timestamp() method, described below.

Examples:

print "Receipt ", ($message->timestamp || 'unknown'), "\n";
nrLines

Returns the number of lines used for the whole message.

sender

Returns exactly one address, which is the originator of this message. The returned Mail::Address object is taken from the Sender header field, unless that field does not exists, in which case the first address from the From field is taken. If none of both provide an address, undef is returned.

Examples:

my $sender = $message->sender;
print "Reply to: ", $sender->format, "\n" if defined $sender;
subject

Returns the message's subject, or the empty string.

Examples:

timestamp

Get a timestamp, doesn't matter how much work it is. If it is impossible to get a time from the header-lines, the current time-of-living is taken.

to

Returns the addresses which are specified on the To header line(s). A list of Mail::Address objects is returned. The people addressed here are the targets of the content, and should read it contents carefully.

Examples:

my @to = $message->to;

The Body

body [BODY]

Return the body of this message. BE WARNED that this returns you an object which may be encoded: use decoded() to get a body with usable data.

With options, a new BODY is set for this message. This is not for normal use unless you understand the consequences: you change the message content without changing the message-ID. The right way to go is via

$message = Mail::Message->buildFromBody($body);  # or
$message = Mail::Message->build($body);          # or
$message = $origmsg->forward(body => $body);

The BODY must be an (sub-)class of Mail::Message::Body. In this case, information from the specified body will be copied into the header. The body object will be encoded if needed, because messages written to file or transmitted shall not contain binary data. The converted body is returned.

When BODY is undef, the current message body will be dissected from the message. All relation will be cut. The body is returned, and can be connected to a different message.

Examples:

my $body      = $msg->body;
my @encoded   = $msg->body->lines;

my $new       = Mail::Message::Body->new(mime_type => 'text/html');
my $converted = $msg->body($new);
decoded OPTIONS

Decodes the body of this message, and returns it as a body object. If there was no encoding, the body object as read from file is passed on, however, some more work will be needed when a serious encoding is encountered. The OPTIONS control how the conversion takes place.

OPTION               DEFAULT
keep                 <false>
result_type          <type of body>
keep => BOOLEAN

Controls whether the decoded result will be kept. If not, the decoding may be performed more than once. However, it will consume extra resources...

result_type => BODYTYPE

Specifies which kind of body should be used for the final result, and eventual intermediate conversion stages. It is not sure that this will be the type of the body returned. BODYTYPE extends Mail::Message::Body.

Examples:

$message->decoded->print(\*OUT);
$message->decoded->print;

my $dec = $message->body($message->decoded);
my $dec = $message->decoded(keep => 1);   # same
encode OPTIONS

Encode the message to a certain format. Read the details in the dedicated manual page Mail::Message::Body::Encode. The OPTIONS which can be specified here are those of the Mail::Message::Body::encode() method.

isMultipart

Check whether this message is a multipart message (has attachments). To find this out, we need at least the header of the message; there is no need to read the body of the message to detect this.

parts ['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER]

Returns the parts of this message. Usually, the term part is used with multipart messages: messages which are encapsulated in the body of a message. To abstract this concept: this method will return you all header-body combinations which are stored within this message. Objects returned are Mail::Message's and Mail::Message::Part's.

The option default to 'ALL', which will return the message itself for single-parts, the nested content of a message/rfc822 object, respectively the parts of a multipart without recursion. In case of 'RECURSE', the parts of multiparts will be collected recursively. This option cannot be combined with the other options, which you may want: it that case you have to test yourself.

'ACTIVE' and 'DELETED' check for the deleted flag on messages and message parts. The FILTER is a code reference, which is called for each message and message part (implies RECURSE).

Examples:

my @parts = $msg->parts;           # $msg not multipart: returns ($msg)
my $parts = $msg->parts('ACTIVE'); # returns ($msg)

$msg->delete;
my @parts = $msg->parts;           # returns ($msg)
my $parts = $msg->parts('ACTIVE'); # returns ()

Access to the Message

file

See Mail::Message::Construct::file()

lines

See Mail::Message::Construct::lines()

string

See Mail::Message::Construct::string()

Labels

label LABEL [,VALUE [LABEL, VALUE] ]

Return the value of the LABEL, optionally after setting it to VALUE. If the VALUE is undef then the label is removed. You may specify a list of LABEL-VALUE pairs at once. In the latter case, the first VALUE is returned.

Labels are used to store knowledge about handling of the message within the folder. Flags about whether a message was read, replied to, or (in some cases) scheduled for deletion.

Some labels are taken from the header's Status and X-Status lines, however folder types like MH define a separate label file.

Examples:

print $message->label('seen');
if($message->label('seen')) {...};
$message->label(seen => 1);
labels

Returns all known labels. In SCALAR context, it returns the knowledge as reference to a hash. This is a reference to the original data, but you shall *not* change that data directly: call label for changes!

In LIST context, you get a list of names which are defined. Be warned that they will not all evaluate to true, although most of them will.

Reading and Writing [internals]

DESTROY

When a message is to accessible anymore by any user's reference, Perl will call DESTROY for final clean-up. In this case, the head and body are released, and de-registered for the folder. You shall not call this yourself!

isDelayed

Check whether the message is delayed (not yet read from file). Returns true or false, dependent on the body type.

labelsToStatus

When the labels were changes, there may be an effect for the Status and/or X-Status header-lines. Whether this update has to take place depends on the type of folder.

readBody PARSER, HEAD [, BODYTYPE]

Read a body of a message. The PARSER is the access to the folder's file, and the HEAD is already read. Information from the HEAD is used to create expectations about the message's length, but also to determine the mime-type and encodings of the body data.

The BODYTYPE determines which kind of body will be made and defaults to the value specified by new(body_type). BODYTYPE may be the name of a body class, or a reference to a routine which returns the body's class when passed the HEAD as only argument.

readFromParser PARSER, [BODYTYPE]

Read one message from file. The PARSER is opened on the file. First readHeader() is called, and the head is stored in the message. Then readBody() is called, to produce a body. Also the body is added to the message without decodings being done.

The optional BODYTYPE may be a body class or a reference to a code which returns a body-class based on the header.

readHead PARSER [,CLASS]

Read a head into an object of the specified CLASS. The CLASS defaults to the head_type option specified at creation of the message (see new()). The PARSER is the access to the folder's file.

statusToLabels

Update the labels according the status lines in the header.

storeBody BODY

Where the body() method can be used to set and get a body, with all the necessary checks, this method is bluntly adding the specified body to the message. No conversions, not checking.

takeMessageId [STRING]

Take the message-id from the STRING, or create one when the undef is specified. If not STRING nor undef is given, the current header of the message is requested for the value of the 'Message-ID' field.

Angles (if present) are removed from the id.

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

printStructure [FILEHANDLE][, INDENT]

See Mail::Message::Construct::printStructure()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.023.

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