Mail::Message - general message object Mail::Message + ::Construct is a Mail::Reporter 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'); See also Mail::Message::Construct. 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. 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 ['ALL'|'ACTIVE'|'DELE... decoded OPTIONS print [FILEHANDLE] destinations MMC printStructure [INDENT] encode OPTIONS MMC read FILEHANDLE|SCALAR|REF-... MR errors MMC reply OPTIONS MMC file MMC replyPrelude [STRING|FIELD|... MMC forward OPTIONS MMC replySubject STRING MMC forwardPostlude MR report [LEVEL] MMC forwardPrelude MR reportAll [LEVEL] MMC forwardSubject STRING send [MAILER], OPTIONS from size get FIELD MMC string guessTimestamp subject isDummy timestamp isMultipart to isPart toplevel label LABEL [,VALUE [LABEL,... MR trace [LEVEL] MMC lines MR warnings MR log [LEVEL [,STRINGS]] The extra methods for extension writers: MR AUTOLOAD MR logPriority LEVEL DESTROY MR logSettings body [BODY] MR notImplemented clone readBody PARSER, HEAD [, BO... coerce MESSAGE readFromParser PARSER, [BOD... head [HEAD] readHead PARSER [,CLASS] MR inGlobalDestruction statusToLabels isDelayed storeBody BODY labels takeMessageId [STRING] labelsToStatus 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' 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". Default type of body to be created for "readBody()". 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". Default type of head to be created for "readHead()". The soft maximum line width of header lines in the folder to write. 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. Flags this message as being modified, from the beginning on. Usually, modification is auto-detected, but there may be reasons to be extra explicit. Is this message from a trusted source? If not, the content must be checked before use.

Message HEAD related
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"; 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; 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; Returns a list of "Mail::Address" objects which contains the combined info of active "To", "Cc", and "Bcc" addresses. Doubles are removed. Returns the message's subject, just as short-cut for writing $message->get('subject') Retrieve the message's id. Every message has a unique message-id. This id is used mainly for recognizing discussion threads. 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"; 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.

Message BODY related
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> Controls whether the decoded result will be kept. If not, the decoding may be performed more than once. However, it will consume extra resources... 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 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
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. 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 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". 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. 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 on single parts: 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 () 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); 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. Returns the size of the whole message in bytes. Returns the number of lines used for the whole message. 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); 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. BE WARNED: the clone of any kind of message will always be a "Mail::Message" object, so a "Mail::Box::Message"'s clone is detached from the folder of its original. When you use "addMessage" to a folder with the cloned message at hand, it will automatically coerce it into the right type to be added. Example: $copy = $msg->clone; See also the "copyTo FOLDER", "moveTo FOLDER", and "reply" methods. 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. 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. 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. 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); 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. 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); Check whether the message is delayed (not yet read from file). Returns true or false, dependent on the body type. 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. (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 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); 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. 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. Update de labels accoring the status lines in the header. 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! Mail::Box-Overview For support and additional documentation, see http://perl.overmeer.net/mailbox/ Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This code is beta, version 2.018. 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.