=encoding utf8 =head1 NAME Mail::Message - general message object =head1 INHERITANCE Mail::Message has extra code in Mail::Message::Construct Mail::Message::Construct::Bounce Mail::Message::Construct::Build Mail::Message::Construct::Forward Mail::Message::Construct::Read Mail::Message::Construct::Rebuild Mail::Message::Construct::Reply Mail::Message::Construct::Text Mail::Message is a Mail::Reporter Mail::Message is extended by Mail::Box::Message Mail::Message::Dummy Mail::Message::Part Mail::Message::Replace::MailInternet =head1 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 Mail::Message::Head $head = $msg->head; my Mail::Message::Body $body = $msg->decoded; $msg->decoded->print($outfile); # Send a simple email Mail::Message->build ( To => 'you@example.com' , From => 'me@example.com' , Subject => "My subject" , data => "Some plain text content" )->send(via => 'postfix'); my $reply_msg = Mail::Message->reply(...); my $frwd_msg = Mail::Message->forward(...); =head1 DESCRIPTION A C object is a container for MIME-encoded message information, as defined by RFC2822. Everything what is not specificaly related to storing the messages in mailboxes (folders) is implemented in this class. Methods which are related to folders is implemented in the L extension. The main methods are L, to get information from a message header field, and L 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 and forwards, are implemented in separate packages which are autoloaded into this class. This means you can simply use these methods as if they are part of this class. Those package add functionality to all kinds of message objects. Extends L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">. =head1 METHODS Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">. =head2 Constructors Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">. =over 4 =item $obj-EB(%options) Create a copy of this message. Returned is a C 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 B be a C object. For example, a L's clone is detached from the folder of its original. When you use L with the cloned message at hand, then the clone will automatically be coerced into the right message type to be added. See also L and L. -Option --Default shallow shallow_body shallow_head =over 2 =item shallow => BOOLEAN When a shallow clone is made, the header and body of the message will not be cloned, but shared. This is quite dangerous: for instance in some folder types, the header fields are used to store folder flags. When one of both shallow clones change the flags, that will update the header and thereby be visible in both. There are situations where a shallow clone can be used safely. For instance, when L is used and you are sure that the original message cannot get undeleted after the move. =item shallow_body => BOOLEAN A rather safe bet, because you are not allowed to modify the body of a message: you may only set a new body with L. =item shallow_head => BOOLEAN Only the head uses is reused, not the body. This is probably a bad choice, because the header fields can be updated, for instance when labels change. =back example: $copy = $msg->clone; =item Mail::Message-EB(%options) -Option --Defined in --Default body undef body_type Mail::Message::Body::Lines deleted field_type undef head undef head_type Mail::Message::Head::Complete labels {} log Mail::Reporter 'WARNINGS' messageId undef modified trace Mail::Reporter 'WARNINGS' trusted =over 2 =item 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 L and L. =item body_type => CLASS Default type of body to be created for L. =item deleted => BOOLEAN Is the file deleted from the start? =item field_type => CLASS =item 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 L. See also L. =item head_type => CLASS Default type of head to be created for L. =item labels => ARRAY|HASH Initial values of the labels. In case of L's, this shall reflect the state the message is in. For newly constructed L's, this may be anything you want, because L will take care of the folder specifics once the message is added to one. =item log => LEVEL =item 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. =item 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. =item trace => LEVEL =item 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. =back =back =head2 Constructing a message =over 4 =item $obj-EB( [<$rg_object|%options>] ) Inherited, see L =item Mail::Message-EB( [$message|$part|$body], $content ) Inherited, see L =item Mail::Message-EB($body, [$head], $headers) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB() Inherited, see L =item $obj-EB(STRING) Inherited, see L =item Mail::Message-EB($fh|STRING|SCALAR|ARRAY, %options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB(%options) Inherited, see L =item $obj-EB( [STRING|$field|$address|ARRAY-$of-$things] ) Inherited, see L =item $obj-EB(STRING) =item Mail::Message-EB(STRING) Inherited, see L =back =head2 The message =over 4 =item $obj-EB() If the message is a part of another message, C returns the reference to the containing body. example: 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->container; # returns $msg->body $nested->toplevel; # returns $msg $msg->container; # returns undef $msg->toplevel; # returns $msg $msg->isPart; # returns false $part->isPart; # returns true =item $obj-EB() 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 L objects, where this will return C. On any extension of C, this will return C. =item $obj-EB() Returns true if the message is a part of another message. This is the case for L extensions of C. =item $obj-EB() Retrieve the message's id. Every message has a unique message-id. This id is used mainly for recognizing discussion threads. =item $obj-EB() Returns a string representing the location of this part. In case the top message is a single message, 'undef' is returned. When it is a multipart, '1' up to the number of multiparts is returned. A multi-level nested part may for instance return '2.5.1'. Usually, this string is very short. Numbering follows the IMAP4 design, see RFC2060 section 6.4.5. =item $obj-EB( [$fh] ) Print the message to the FILE-HANDLE, which defaults to the selected filehandle, without the encapsulation sometimes required by a folder type, like L does. example: $message->print(\*STDERR); # to the error output $message->print; # to the selected file my $out = IO::File->new('out', 'w'); $message->print($out); # no encapsulation: no folder $message->write($out); # with encapsulation: is folder. =item $obj-EB( [$mailer], %options ) Transmit the message to anything outside this Perl program. Returns false when sending failed even after retries. The optional $mailer is a L 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, and a mixture of what is usable for the creation of the mailer object and the sending itself. Therefore, see for possible options L and L. That object also provides a C method which gives more low-level control. example: $message->send; is short (but little less flexibile) for my $mailer = Mail::Transport::SMTP->new(@smtpopts); $mailer->send($message, @sendopts); See examples/send.pl in the distribution of L. example: $message->send(via => 'sendmail') =item $obj-EB() Returns an estimated size of the whole message in bytes. In many occasions, the functions which process the message further, for instance L or L will need to add/change header lines or add CR characters, so the size is only an estimate with a few percent margin of the real result. The computation assumes that each line ending is represented by one character (like UNIX, MacOS, and sometimes Cygwin), and not two characters (like Windows and sometimes Cygwin). If you write the message to file on a system which uses CR and LF to end a single line (all Windows versions), the result in that file will be at least L larger than this method returns. =item $obj-EB() Returns a reference to the main message, which will be the current message if the message is not part of another message. =item $obj-EB( [$fh] ) Write the message to the FILE-HANDLE, which defaults to the selected $fh, with all surrounding information which is needed to put it correctly in a folder file. In most cases, the result of C will be the same as with L. The main exception is for Mbox folder messages, which will get printed with their leading 'From ' line and a trailing blank. Each line of their body which starts with 'From ' will have an 'E' added in front. =back =head2 The header =over 4 =item $obj-EB() Returns the addresses which are specified on the C header line (or lines) A list of L objects is returned. C stands for I: 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. =item $obj-EB() Returns the addresses which are specified on the C header line (or lines) A list of L objects is returned. C stands for I; the people addressed on this line receive the message informational, and are usually not expected to reply on its content. =item $obj-EB() Method has been removed for reasons of consistency. Use L or C<< $msg->head->get('Date') >>. =item $obj-EB() Returns a list of L objects which contains the combined info of active C, C, and C addresses. Double addresses are removed if detectable. =item $obj-EB() Returns the addresses from the senders. It is possible to have more than one address specified in the C field of the message, according to the specification. Therefore a list of L objects is returned, which usually has length 1. If you need only one address from a sender, for instance to create a "original message by" line in constructed forwarded message body, then use L. example: using from() to get all sender addresses my @from = $message->from; =item $obj-EB($fieldname) Returns the value which is stored in the header field with the specified name. The $fieldname is case insensitive. The I of the field is returned, stripped from any attributes. See L. If the field has multiple appearances in the header, only the last instance is returned. If you need more complex handing of fields, then call L yourself. See L when you want to be smart, doing the better (but slower) job. example: the get() short-cut for header fields print $msg->get('Content-Type'), "\n"; Is equivalent to: print $msg->head->get('Content-Type')->body, "\n"; =item $obj-EB() Return an estimate on the time this message was sent. The data is derived from the header, where it can be derived from the C and C lines. For MBox-like folders you may get the date from the from-line as well. This method may return C if the header is not parsed or only partially known. If you require a time, then use the L method, described below. example: using guessTimestamp() to get a transmission date print "Receipt ", ($message->timestamp || 'unknown'), "\n"; =item $obj-EB( [$head] ) Return (optionally after setting) the $head of this message. The head must be an (sub-)class of L. 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. example: my $header = Mail::Message::Head->new; $msg->head($header); # set my $head = $msg->head; # get =item $obj-EB() Returns the number of lines used for the whole message. =item $obj-EB() Returns exactly one address, which is the originator of this message. The returned L object is taken from the C header field, unless that field does not exists, in which case the first address from the C field is taken. If none of both provide an address, C is returned. example: using sender() to get exactly one sender address my $sender = $message->sender; print "Reply to: ", $sender->format, "\n" if defined $sender; =item $obj-EB($fieldname) Study the content of a field, like L does, with as main difference that a L object is returned. These objects stringify to an utf8 decoded representation of the data contained in the field, where L does not decode. When the field does not exist, then C is returned. See L. example: the study() short-cut for header fields print $msg->study('to'), "\n"; Is equivalent to: print $msg->head->study('to'), "\n"; # and print $msg->head->get('to')->study, "\n"; or better: if(my $to = $msg->study('to')) { print "$to\n" } if(my $to = $msg->get('to')) { print $to->study, "\n" } =item $obj-EB() Returns the message's subject, or the empty string. The subject may have encoded characters in it; use L to get rit of that. example: using subject() to get the message's subject print $msg->subject; print $msg->study('subject'); =item $obj-EB() Get a good timestamp for the message, doesn't matter how much work it is. The value returned is compatible with the platform dependent result of function time(). In these days, the timestamp as supplied by the message (in the C field) is not trustable at all: many spammers produce illegal or unreal dates to influence their location in the displayed folder. To start, the received headers are tried for a date (see L) and only then the C field. In very rare cases, only with some locally produced messages, no stamp can be found. =item $obj-EB() Returns the addresses which are specified on the C header line (or lines). A list of L objects is returned. The people addressed here are the targets of the content, and should read it contents carefully. example: using to() to get all primar destination addresses my @to = $message->to; =back =head2 The body =over 4 =item $obj-EB( [$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 B 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 L. 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 C, 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. example: my $body = $msg->body; my @encoded = $msg->body->lines; my $new = Mail::Message::Body->new(mime_type => 'text/html'); my $converted = $msg->body($new); =item $obj-EB() Returns the content type header line, or C if it is not defined. The parameters will be stripped off. =item $obj-EB(%options) Decodes the body of this message, and returns it as a body object. Short for C<< $msg->body->decoded >> All %options are passed-on. =item $obj-EB(%options) Encode the message to a certain format. Read the details in the dedicated manual page L. The %options which can be specified here are those of the L method. =item $obj-EB() 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. =item $obj-EB() Returns C for C messages and message parts. =item $obj-EB( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] ) Returns the I of this message. Maybe a bit inconvenient: it returns the message itself when it is not a multipart. Usually, the term I is used with I 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 B the multipart and message/rfc822 wrappers. Objects returned are C's and L'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 part of the message; each part as C would return. example: 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 () =back =head2 Flags =over 4 =item $obj-EB() Flag the message to be deleted, which is a shortcut for $msg->label(deleted => time); The real deletion only takes place on a synchronization of the folder. See L as well. The time stamp of the moment of deletion is stored as value, but that is not always preserved in the folder (depends on the implementation). When the same message is deleted more than once, the first time stamp will stay. example: $message->delete; $message->deleted(1); # exactly the same $message->label(deleted => 1); delete $message; =item $obj-EB( [BOOLEAN] ) Set the delete flag for this message. Without argument, the method returns the same as L, which is preferred. When a true value is given, L is called. example: $message->deleted(1); # delete $message->delete; # delete (preferred) $message->deleted(0); # undelete if($message->deleted) {...} # check if($message->isDeleted) {...} # check (preferred) =item $obj-EB() Short-cut for $msg->label('deleted') For some folder types, you will get the time of deletion in return. This depends on the implementation. example: next if $message->isDeleted; if(my $when = $message->isDeleted) { print scalar localtime $when; } =item $obj-EB() Returns whether this message is flagged as being modified. Modifications are changes in header lines, when a new body is set to the message (dangerous), or when labels change. =item $obj-EB