NAME

Mail::Message - general message object

CLASS HIERARCHY

Mail::Message + ::Construct
is a Mail::Reporter

SYNOPSIS

use Mail::Box::Manager;
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => $MAIL);
my $msg    = $folder->message(2);    # $msg isa Mail::Message

$msg->decoded->print($outfile);

my Mail::Message $construct  = Mail::Message->new;
my Mail::Message $construct  = Mail::Message->build(...);
my Mail::Message::Head $head = $msg->head;
my Mail::Message::Body $body = $msg->decoded;
my $subject = $msg->get('subject');

DESCRIPTION

A Mail::Message object is a container for message information read from a file. Everything what is not folder related will be found here.

Complex message handling (like construction of replies) are handled by the Mail::Message::Construct package which is autoloaded. That package adds functionality to the Mail::Message objects.

The main methods are get() -to get information from a message header- and decoded() to get the intented content of a message.

METHOD INDEX

Methods prefixed with an abbreviation are described in Mail::Reporter (MR), Mail::Message::Construct (MMC).

The general methods for Mail::Message objects:

    bcc                                  messageId
MMC bounce OPTIONS                       modified [BOOL]
MMC build [MESSAGE|BODY], CONTENT        new OPTIONS
MMC buildFromBody BODY, HEADERS          nrLines
    cc                                   parent
    date                                 parts
    decoded OPTIONS                      print [FILEHANDLE]
    destinations                         printUndisclosed [FILEHANDLE]
    encode OPTIONS                   MMC read FILEHANDLE|SCALAR|REF-...
 MR errors                           MMC reply OPTIONS
MMC forward OPTIONS                  MMC replyPrelude [STRING|FIELD|...
MMC forwardPostlude                  MMC replySubject STRING
MMC forwardPrelude                    MR report [LEVEL]
MMC forwardSubject STRING             MR reportAll [LEVEL]
    from                                 send [MAILER], OPTIONS
    get FIELD                            size
    guessTimestamp                       subject
    isDummy                              timestamp
    isMultipart                          to
    isPart                               toplevel
    label LABEL [,VALUE [LABEL,...    MR trace [LEVEL]
 MR log [LEVEL [,STRINGS]]            MR warnings

The extra methods for extension writers:

MR AUTOLOAD                             labelsToStatus
   DESTROY                           MR logPriority LEVEL
   body [BODY]                       MR logSettings
   clone                             MR notImplemented
   coerce MESSAGE                       readBody PARSER, HEAD [, BO...
   head [HEAD]                          readFromParser PARSER, [BOD...
MR inGlobalDestruction                  readHead PARSER [,CLASS]
   isDelayed                            statusToLabels
   labels                               storeBody BODY

METHODS

new OPTIONS

Create a new message object. The message's head and body will be read later, unless specified at construction.

OPTION            DESCRIBED IN       DEFAULT
body              Mail::Message      undef
head              Mail::Message      undef
log               Mail::Reporter     'WARNINGS'
messageId         Mail::Message      undef
modified          Mail::Message      0
trace             Mail::Reporter     'WARNINGS'
trusted           Mail::Message      0
head_wrap         Mail::Message      72

Only for extension writers:

OPTION            DESCRIBED IN       DEFAULT
body_type         Mail::Message      'Mail::Message::Body::Lines'
field_type        Mail::Message      undef
head_type         Mail::Message      'Mail::Message::Head::Complete'

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.
body_type => CLASS

Default type of body to be created for readBody().
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.
head_type => CLASS

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

The soft maximum line width of header lines in the folder to write.
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 => BOOL

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

Is this message from a trusted source? If not, the content must be checked before use.

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, the last instance is returned.

The field name is case insensitive. Only the `body' of the field is returned, not the comment (after ';'). If you need more complex handing of fields, then call

Example:

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

Is equivalent to:

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

from

Returns the address of the sender. This can only be one address. Of this is a bounced message, the Mail::Address representation of the Resent-From line is returned. Otherwise, the From line is scanned. If that line is not present, the Sender line is probed. Otherwise, undef is returned.

Example:

my $from = $message->from;

to

cc

bcc

date

Returns the addresses which are defined for the indicated header-lines. Most methods return a list of Mail::Message objects, except from which returns one address only, and date returns the last date as string.

These methods are a little more complicated than just fetching these header lines by the existence of Resent- header lines. These Resent- lines are added when messages get bounced, and take preference over their counterparts. Only the last Resent- line can be used.

Examples:

my @to   = $message->to;
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.

subject

Returns the message's subject, just as short-cut for writing

$message->get('subject')

messageId

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

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";

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.

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            DESCRIBED IN          DEFAULT
keep              Mail::Message         0
result_type       Mail::Message         <type of the body>

keep => BOOL

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 encode() method.

Other methods

modified [BOOL]

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

isPart

toplevel

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. isPart returns true if the message is a part of another message. toplevel returns a reference to the main message, which will be the current message if the message is not part of another 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

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 extention of Mail::Message, this will return false.

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

Returns the parts of this message. If the message is not a multi-part, it will be returned itself. However, if this is a multi-part then a list with all the parts is returned.

print [FILEHANDLE]

printUndisclosed [FILEHANDLE]

Print the message to the FILE-HANDLE, which defaults to the selected filehandle. In the former case of print including the Bcc and Resent-Bcc lines, in the latter case without them.

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. Writing

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

is a short for

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

However, when the MAILER is not specified, one will be auto-generated via Mail::Transport::new. This object will be re-used. For instance

$message->send(@sendopts);

is equivalent to

Mail::Transport->new->send($message, @sendopts);

The OPTIONS are mailer specific.

size

Returns the size of the whole message in bytes.

nrLines

Returns the number of lines used for the whole message.

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 seperate label file.

Examples:

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

METHODS for extension writers

clone

Create a copy of this message. The head and body, the log and trace levels are taken. The copy will not be added to any folder automatically.

Example:

$copy = $msg->clone;

See also the copyTo FOLDER, moveTo FOLDER, and reply methods.

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.

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 the body_type option at message creation (see new). 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.

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. The body must be an (sub-)class of Mail::Message::Body. In this case, information from the specified body will be compied 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 disected from the message. All relation will be cut. The body is returned, and can be connected to a diffent 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);

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.

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 LABALS hash. They are added later.

Example:

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

isDelayed

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

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.

coerce MESSAGE

(Class method) Coerce a MESSAGE into a Mail::Message. In some occations, 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.

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

MIME::Entity's, using Mail::Message::Convert::MimeEntity
Mail::Internet's, using Mail::Message::Convert::MimeEntity
any extension of Mail::Message is left untouched

Example:

my $message = Mail::Message->new(...);
my $coerced = Mail::Box::MBox::Message->coerce($message);
# now $coerced is a Mail::Box::Mbox::Message

It is better to use (when the message will be stored in that folder):

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

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.

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.

statusToLabels

Update de labels accoring the status lines in the header.

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!

AUTHOR

VERSION

This code is beta, version 2.013.

To install Mail::Box, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Box

CPAN shell

perl -MCPAN -e shell
install Mail::Box

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

CLASS HIERARCHY

SYNOPSIS

DESCRIPTION

METHOD INDEX

METHODS

Message HEAD related

Message BODY related

Other methods

METHODS for extension writers

SEE ALSO

AUTHOR

VERSION

Module Install Instructions