1Mail::Message(3) User Contributed Perl Documentation Mail::Message(3)
2
6 Mail::Message - general message object
7
9 Mail::Message has extra code in
10 Mail::Message::Construct
11 Mail::Message::Construct::Bounce
12 Mail::Message::Construct::Build
13 Mail::Message::Construct::Forward
14 Mail::Message::Construct::Read
15 Mail::Message::Construct::Rebuild
16 Mail::Message::Construct::Reply
17 Mail::Message::Construct::Text
18 Mail::Message
20 is a Mail::Reporter
21 Mail::Message is extended by
23 Mail::Box::Message
24 Mail::Message::Dummy
25 Mail::Message::Part
26 Mail::Message::Replace::MailInternet
27
29 use Mail::Box::Manager;
30 my $mgr = Mail::Box::Manager->new;
31 my $folder = $mgr->open(folder => 'InBox');
32 my $msg = $folder->message(2); # $msg is a Mail::Message now
33 my $subject = $msg->subject; # The message's subject
35 my @cc = $msg->cc; # List of Mail::Address'es
36 my Mail::Message::Head $head = $msg->head;
38 my Mail::Message::Body $body = $msg->decoded;
39 $msg->decoded->print($outfile);
40 # Send a simple email
42 Mail::Message->build
43 ( To => 'you@example.com'
44 , From => 'me@example.com'
45 , Subject => "My subject"
46 , data => "Some plain text content"
47 )->send(via => 'postfix');
48 my $reply_msg = Mail::Message->reply(...);
50 my $frwd_msg = Mail::Message->forward(...);
51
53 A "Mail::Message" object is a container for MIME-encoded message
54 information, as defined by RFC2822. Everything what is not specificaly
55 related to storing the messages in mailboxes (folders) is implemented
56 in this class. Methods which are related to folders is implemented in
57 the Mail::Box::Message extension.
58 The main methods are get(), to get information from a message header
60 field, and decoded() to get the intended content of a message. But
61 there are many more which can assist your program.
62 Complex message handling, like construction of replies and forwards,
64 are implemented in separate packages which are autoloaded into this
65 class. This means you can simply use these methods as if they are part
66 of this class. Those package add functionality to all kinds of message
67 objects.
68 Extends "DESCRIPTION" in Mail::Reporter.
70
72 Extends "METHODS" in Mail::Reporter.
73 Constructors
75 Extends "Constructors" in Mail::Reporter.
76 $obj->clone(%options)
78 Create a copy of this message. Returned is a "Mail::Message"
79 object. The head and body, the log and trace levels are taken.
80 Labels are copied with the message, but the delete and modified
81 flags are not.
82 BE WARNED: the clone of any kind of message (or a message part)
84 will always be a "Mail::Message" object. For example, a
85 Mail::Box::Message's clone is detached from the folder of its
86 original. When you use Mail::Box::addMessage() with the cloned
87 message at hand, then the clone will automatically be coerced into
88 the right message type to be added.
89 See also Mail::Box::Message::copyTo() and
91 Mail::Box::Message::moveTo().
92 -Option --Default
94 shallow <false>
95 shallow_body <false>
96 shallow_head <false>
97 shallow => BOOLEAN
99 When a shallow clone is made, the header and body of the message
100 will not be cloned, but shared. This is quite dangerous: for
101 instance in some folder types, the header fields are used to
102 store folder flags. When one of both shallow clones change the
103 flags, that will update the header and thereby be visible in
104 both.
105 There are situations where a shallow clone can be used safely.
107 For instance, when Mail::Box::Message::moveTo() is used and you
108 are sure that the original message cannot get undeleted after the
109 move.
110 shallow_body => BOOLEAN
112 A rather safe bet, because you are not allowed to modify the body
113 of a message: you may only set a new body with body().
114 shallow_head => BOOLEAN
116 Only the head uses is reused, not the body. This is probably a
117 bad choice, because the header fields can be updated, for
118 instance when labels change.
119 example:
121 $copy = $msg->clone;
123 Mail::Message->new(%options)
125 -Option --Defined in --Default
126 body undef
127 body_type Mail::Message::Body::Lines
128 deleted <false>
129 field_type undef
130 head undef
131 head_type Mail::Message::Head::Complete
132 labels {}
133 log Mail::Reporter 'WARNINGS'
134 messageId undef
135 modified <false>
136 trace Mail::Reporter 'WARNINGS'
137 trusted <false>
138 body => OBJECT
140 Instantiate the message with a body which has been created
141 somewhere before the message is constructed. The OBJECT must be
142 a sub-class of Mail::Message::Body. See also body() and
143 storeBody().
144 body_type => CLASS
146 Default type of body to be created for readBody().
147 deleted => BOOLEAN
149 Is the file deleted from the start?
150 field_type => CLASS
152 head => OBJECT
153 Instantiate the message with a head which has been created
154 somewhere before the message is constructed. The OBJECT must be
155 a (sub-)class of Mail::Message::Head. See also head().
156 head_type => CLASS
158 Default type of head to be created for readHead().
159 labels => ARRAY|HASH
161 Initial values of the labels. In case of Mail::Box::Message's,
162 this shall reflect the state the message is in. For newly
163 constructed Mail::Message's, this may be anything you want,
164 because coerce() will take care of the folder specifics once the
165 message is added to one.
166 log => LEVEL
168 messageId => STRING
169 The id on which this message can be recognized. If none
170 specified and not defined in the header --but one is needed--
171 there will be one assigned to the message to be able to pass
172 unique message-ids between objects.
173 modified => BOOLEAN
175 Flags this message as being modified from the beginning on.
176 Usually, modification is auto-detected, but there may be reasons
177 to be extra explicit.
178 trace => LEVEL
180 trusted => BOOLEAN
181 Is this message from a trusted source? If not, the content must
182 be checked before use. This checking will be performed when the
183 body data is decoded or used for transmission.
184 Constructing a message
186 $obj->bounce( [<$rg_object|%options>] )
187 Inherited, see "Constructing a message" in
188 Mail::Message::Construct::Bounce
189 Mail::Message->build( [$message|$part|$body], $content )
191 Inherited, see "Constructing a message" in
192 Mail::Message::Construct::Build
193 Mail::Message->buildFromBody($body, [$head], $headers)
195 Inherited, see "Constructing a message" in
196 Mail::Message::Construct::Build
197 $obj->forward(%options)
199 Inherited, see "Constructing a message" in
200 Mail::Message::Construct::Forward
201 $obj->forwardAttach(%options)
203 Inherited, see "Constructing a message" in
204 Mail::Message::Construct::Forward
205 $obj->forwardEncapsulate(%options)
207 Inherited, see "Constructing a message" in
208 Mail::Message::Construct::Forward
209 $obj->forwardInline(%options)
211 Inherited, see "Constructing a message" in
212 Mail::Message::Construct::Forward
213 $obj->forwardNo(%options)
215 Inherited, see "Constructing a message" in
216 Mail::Message::Construct::Forward
217 $obj->forwardPostlude()
219 Inherited, see "Constructing a message" in
220 Mail::Message::Construct::Forward
221 $obj->forwardPrelude()
223 Inherited, see "Constructing a message" in
224 Mail::Message::Construct::Forward
225 $obj->forwardSubject(STRING)
227 Inherited, see "Constructing a message" in
228 Mail::Message::Construct::Forward
229 Mail::Message->read($fh|STRING|SCALAR|ARRAY, %options)
231 Inherited, see "Constructing a message" in
232 Mail::Message::Construct::Read
233 $obj->rebuild(%options)
235 Inherited, see "Constructing a message" in
236 Mail::Message::Construct::Rebuild
237 $obj->reply(%options)
239 Inherited, see "Constructing a message" in
240 Mail::Message::Construct::Reply
241 $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
243 Inherited, see "Constructing a message" in
244 Mail::Message::Construct::Reply
245 $obj->replySubject(STRING)
247 Mail::Message->replySubject(STRING)
248 Inherited, see "Constructing a message" in
249 Mail::Message::Construct::Reply
250 The message
252 $obj->container()
253 If the message is a part of another message, "container" returns
254 the reference to the containing body.
255 example:
257 my Mail::Message $msg = ...
259 return unless $msg->body->isMultipart;
260 my $part = $msg->body->part(2);
261 return unless $part->body->isMultipart;
263 my $nested = $part->body->part(3);
264 $nested->container; # returns $msg->body
266 $nested->toplevel; # returns $msg
267 $msg->container; # returns undef
268 $msg->toplevel; # returns $msg
269 $msg->isPart; # returns false
270 $part->isPart; # returns true
271 $obj->isDummy()
273 Dummy messages are used to fill holes in linked-list and such,
274 where only a message-id is known, but not the place of the header
275 of body data.
276 This method is also available for Mail::Message::Dummy objects,
278 where this will return "true". On any extension of
279 "Mail::Message", this will return "false".
280 $obj->isPart()
282 Returns true if the message is a part of another message. This is
283 the case for Mail::Message::Part extensions of "Mail::Message".
284 $obj->messageId()
286 Retrieve the message's id. Every message has a unique message-id.
287 This id is used mainly for recognizing discussion threads.
288 $obj->partNumber()
290 Returns a string representing the location of this part. In case
291 the top message is a single message, 'undef' is returned. When it
292 is a multipart, '1' up to the number of multiparts is returned. A
293 multi-level nested part may for instance return '2.5.1'.
294 Usually, this string is very short. Numbering follows the IMAP4
296 design, see RFC2060 section 6.4.5.
297 $obj->print( [$fh] )
299 Print the message to the FILE-HANDLE, which defaults to the
300 selected filehandle, without the encapsulation sometimes required
301 by a folder type, like write() does.
302 example:
304 $message->print(\*STDERR); # to the error output
306 $message->print; # to the selected file
307 my $out = IO::File->new('out', 'w');
309 $message->print($out); # no encapsulation: no folder
310 $message->write($out); # with encapsulation: is folder.
311 $obj->send( [$mailer], %options )
313 Transmit the message to anything outside this Perl program.
314 Returns false when sending failed even after retries.
315 The optional $mailer is a Mail::Transport::Send object. When the
317 $mailer is not specified, one will be created and kept as default
318 for the next messages as well.
319 The %options are mailer specific, and a mixture of what is usable
321 for the creation of the mailer object and the sending itself.
322 Therefore, see for possible options Mail::Transport::Send::new()
323 and Mail::Transport::Send::send(). That object also provides a
324 "trySend()" method which gives more low-level control.
325 example:
327 $message->send;
329 is short (but little less flexibile) for
331 my $mailer = Mail::Transport::SMTP->new(@smtpopts);
333 $mailer->send($message, @sendopts);
334 See examples/send.pl in the distribution of Mail::Box.
336 example:
338 $message->send(via => 'sendmail')
340 $obj->size()
342 Returns an estimated size of the whole message in bytes. In many
343 occasions, the functions which process the message further, for
344 instance send() or print() will need to add/change header lines or
345 add CR characters, so the size is only an estimate with a few
346 percent margin of the real result.
347 The computation assumes that each line ending is represented by one
349 character (like UNIX, MacOS, and sometimes Cygwin), and not two
350 characters (like Windows and sometimes Cygwin). If you write the
351 message to file on a system which uses CR and LF to end a single
352 line (all Windows versions), the result in that file will be at
353 least nrLines() larger than this method returns.
354 $obj->toplevel()
356 Returns a reference to the main message, which will be the current
357 message if the message is not part of another message.
358 $obj->write( [$fh] )
360 Write the message to the FILE-HANDLE, which defaults to the
361 selected $fh, with all surrounding information which is needed to
362 put it correctly in a folder file.
363 In most cases, the result of "write" will be the same as with
365 print(). The main exception is for Mbox folder messages, which
366 will get printed with their leading 'From ' line and a trailing
367 blank. Each line of their body which starts with 'From ' will have
368 an '>' added in front.
369 The header
371 $obj->bcc()
372 Returns the addresses which are specified on the "Bcc" header line
373 (or lines) A list of Mail::Address objects is returned. "Bcc"
374 stands for Blind Carbon Copy: destinations of the message which are
375 not listed in the messages actually sent. So, this field will be
376 empty for received messages, but may be present in messages you
377 construct yourself.
378 $obj->cc()
380 Returns the addresses which are specified on the "Cc" header line
381 (or lines) A list of Mail::Address objects is returned. "Cc"
382 stands for Carbon Copy; the people addressed on this line receive
383 the message informational, and are usually not expected to reply on
384 its content.
385 $obj->date()
387 Method has been removed for reasons of consistency. Use
388 timestamp() or "$msg->head->get('Date')".
389 $obj->destinations()
391 Returns a list of Mail::Address objects which contains the combined
392 info of active "To", "Cc", and "Bcc" addresses. Double addresses
393 are removed if detectable.
394 $obj->from()
396 Returns the addresses from the senders. It is possible to have
397 more than one address specified in the "From" field of the message,
398 according to the specification. Therefore a list of Mail::Address
399 objects is returned, which usually has length 1.
400 If you need only one address from a sender, for instance to create
402 a "original message by" line in constructed forwarded message body,
403 then use sender().
404 example: using from() to get all sender addresses
406 my @from = $message->from;
408 $obj->get($fieldname)
410 Returns the value which is stored in the header field with the
411 specified name. The $fieldname is case insensitive. The unfolded
412 body of the field is returned, stripped from any attributes. See
413 Mail::Message::Field::body().
414 If the field has multiple appearances in the header, only the last
416 instance is returned. If you need more complex handing of fields,
417 then call Mail::Message::Head::get() yourself. See study() when
418 you want to be smart, doing the better (but slower) job.
419 example: the get() short-cut for header fields
421 print $msg->get('Content-Type'), "\n";
423 Is equivalent to:
425 print $msg->head->get('Content-Type')->body, "\n";
427 $obj->guessTimestamp()
429 Return an estimate on the time this message was sent. The data is
430 derived from the header, where it can be derived from the "date"
431 and "received" lines. For MBox-like folders you may get the date
432 from the from-line as well.
433 This method may return "undef" if the header is not parsed or only
435 partially known. If you require a time, then use the timestamp()
436 method, described below.
437 example: using guessTimestamp() to get a transmission date
439 print "Receipt ", ($message->timestamp || 'unknown'), "\n";
441 $obj->head( [$head] )
443 Return (optionally after setting) the $head of this message. The
444 head must be an (sub-)class of Mail::Message::Head. When the head
445 is added, status information is taken from it and transformed into
446 labels. More labels can be added by the LABELS hash. They are
447 added later.
448 example:
450 my $header = Mail::Message::Head->new;
452 $msg->head($header); # set
453 my $head = $msg->head; # get
454 $obj->nrLines()
456 Returns the number of lines used for the whole message.
457 $obj->sender()
459 Returns exactly one address, which is the originator of this
460 message. The returned Mail::Address object is taken from the
461 "Sender" header field, unless that field does not exists, in which
462 case the first address from the "From" field is taken. If none of
463 both provide an address, "undef" is returned.
464 example: using sender() to get exactly one sender address
466 my $sender = $message->sender;
468 print "Reply to: ", $sender->format, "\n" if defined $sender;
469 $obj->study($fieldname)
471 Study the content of a field, like get() does, with as main
472 difference that a Mail::Message::Field::Full object is returned.
473 These objects stringify to an utf8 decoded representation of the
474 data contained in the field, where get() does not decode. When the
475 field does not exist, then "undef" is returned. See
476 Mail::Message::Field::study().
477 example: the study() short-cut for header fields
479 print $msg->study('to'), "\n";
481 Is equivalent to:
483 print $msg->head->study('to'), "\n"; # and
485 print $msg->head->get('to')->study, "\n";
486 or better:
488 if(my $to = $msg->study('to')) { print "$to\n" }
489 if(my $to = $msg->get('to')) { print $to->study, "\n" }
490 $obj->subject()
492 Returns the message's subject, or the empty string. The subject
493 may have encoded characters in it; use study() to get rit of that.
494 example: using subject() to get the message's subject
496 print $msg->subject;
498 print $msg->study('subject');
499 $obj->timestamp()
501 Get a good timestamp for the message, doesn't matter how much work
502 it is. The value returned is compatible with the platform
503 dependent result of function time().
504 In these days, the timestamp as supplied by the message (in the
506 "Date" field) is not trustable at all: many spammers produce
507 illegal or unreal dates to influence their location in the
508 displayed folder.
509 To start, the received headers are tried for a date (see
511 Mail::Message::Head::Complete::recvstamp()) and only then the
512 "Date" field. In very rare cases, only with some locally produced
513 messages, no stamp can be found.
514 $obj->to()
516 Returns the addresses which are specified on the "To" header line
517 (or lines). A list of Mail::Address objects is returned. The
518 people addressed here are the targets of the content, and should
519 read it contents carefully.
520 example: using to() to get all primar destination addresses
522 my @to = $message->to;
524 The body
526 $obj->body( [$body] )
527 Return the body of this message. BE WARNED that this returns you
528 an object which may be encoded: use decoded() to get a body with
529 usable data.
530 With options, a new $body is set for this message. This is not for
532 normal use unless you understand the consequences: you change the
533 message content without changing the message-ID. The right way to
534 go is via
535 $message = Mail::Message->buildFromBody($body); # or
537 $message = Mail::Message->build($body); # or
538 $message = $origmsg->forward(body => $body);
539 The $body must be an (sub-)class of Mail::Message::Body. In this
541 case, information from the specified body will be copied into the
542 header. The body object will be encoded if needed, because
543 messages written to file or transmitted shall not contain binary
544 data. The converted body is returned.
545 When $body is "undef", the current message body will be dissected
547 from the message. All relation will be cut. The body is returned,
548 and can be connected to a different message.
549 example:
551 my $body = $msg->body;
553 my @encoded = $msg->body->lines;
554 my $new = Mail::Message::Body->new(mime_type => 'text/html');
556 my $converted = $msg->body($new);
557 $obj->contentType()
559 Returns the content type header line, or "text/plain" if it is not
560 defined. The parameters will be stripped off.
561 $obj->decoded(%options)
563 Decodes the body of this message, and returns it as a body object.
564 Short for "$msg->body->decoded" All %options are passed-on.
565 $obj->encode(%options)
567 Encode the message to a certain format. Read the details in the
568 dedicated manual page Mail::Message::Body::Encode. The %options
569 which can be specified here are those of the
570 Mail::Message::Body::encode() method.
571 $obj->isMultipart()
573 Check whether this message is a multipart message (has
574 attachments). To find this out, we need at least the header of the
575 message; there is no need to read the body of the message to detect
576 this.
577 $obj->isNested()
579 Returns "true" for "message/rfc822" messages and message parts.
580 $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
582 Returns the parts of this message. Maybe a bit inconvenient: it
583 returns the message itself when it is not a multipart.
584 Usually, the term part is used with multipart messages: messages
586 which are encapsulated in the body of a message. To abstract this
587 concept: this method will return you all header-body combinations
588 which are stored within this message except the multipart and
589 message/rfc822 wrappers. Objects returned are "Mail::Message"'s
590 and Mail::Message::Part's.
591 The option default to 'ALL', which will return the message itself
593 for single-parts, the nested content of a message/rfc822 object,
594 respectively the parts of a multipart without recursion. In case
595 of 'RECURSE', the parts of multiparts will be collected
596 recursively. This option cannot be combined with the other
597 options, which you may want: it that case you have to test
598 yourself.
599 'ACTIVE' and 'DELETED' check for the deleted flag on messages and
601 message parts. The $filter is a code reference, which is called
602 for each part of the message; each part as "RECURSE" would return.
603 example:
605 my @parts = $msg->parts; # $msg not multipart: returns ($msg)
607 my $parts = $msg->parts('ACTIVE'); # returns ($msg)
608 $msg->delete;
610 my @parts = $msg->parts; # returns ($msg)
611 my $parts = $msg->parts('ACTIVE'); # returns ()
612 Flags
614 $obj->delete()
615 Flag the message to be deleted, which is a shortcut for
616 $msg->label(deleted => time); The real deletion only takes place
617 on a synchronization of the folder. See deleted() as well.
618 The time stamp of the moment of deletion is stored as value, but
620 that is not always preserved in the folder (depends on the
621 implementation). When the same message is deleted more than once,
622 the first time stamp will stay.
623 example:
625 $message->delete;
627 $message->deleted(1); # exactly the same
628 $message->label(deleted => 1);
629 delete $message;
630 $obj->deleted( [BOOLEAN] )
632 Set the delete flag for this message. Without argument, the method
633 returns the same as isDeleted(), which is preferred. When a true
634 value is given, delete() is called.
635 example:
637 $message->deleted(1); # delete
639 $message->delete; # delete (preferred)
640 $message->deleted(0); # undelete
642 if($message->deleted) {...} # check
644 if($message->isDeleted) {...} # check (preferred)
645 $obj->isDeleted()
647 Short-cut for
648 $msg->label('deleted')
649 For some folder types, you will get the time of deletion in return.
651 This depends on the implementation.
652 example:
654 next if $message->isDeleted;
656 if(my $when = $message->isDeleted) {
658 print scalar localtime $when;
659 }
660 $obj->isModified()
662 Returns whether this message is flagged as being modified.
663 Modifications are changes in header lines, when a new body is set
664 to the message (dangerous), or when labels change.
665 $obj->label($label|PAIRS)
667 Return the value of the $label, optionally after setting some
668 values. In case of setting values, you specify key-value PAIRS.
669 Labels are used to store knowledge about handling of the message
671 within the folder. Flags about whether a message was read, replied
672 to, or scheduled for deletion.
673 Some labels are taken from the header's "Status" and "X-Status"
675 lines. Folder types like MH define a separate label file, and
676 Maildir adds letters to the message filename. But the MailBox
677 labels are always the same.
678 example:
680 print $message->label('seen');
682 if($message->label('seen')) {...};
683 $message->label(seen => 1);
684 $message->label(deleted => 1); # same as $message->delete
686 $obj->labels()
688 Returns all known labels. In SCALAR context, it returns the
689 knowledge as reference to a hash. This is a reference to the
690 original data, but you shall *not* change that data directly: call
691 "label" for changes!
692 In LIST context, you get a list of names which are defined. Be
694 warned that they will not all evaluate to true, although most of
695 them will.
696 $obj->labelsToStatus()
698 When the labels were changed, that may effect the "Status" and/or
699 "X-Status" header lines of mbox messages. Read about the relation
700 between these fields and the labels in the DETAILS chapter.
701 The method will carefully only affect the result of modified() when
703 there is a real change of flags, so not for each call to label().
704 $obj->modified( [BOOLEAN] )
706 Returns (optionally after setting) whether this message is flagged
707 as being modified. See isModified().
708 $obj->statusToLabels()
710 Update the labels according the status lines in the header. See
711 the description in the DETAILS chapter.
712 The whole message as text
714 $obj->file()
715 Inherited, see "The whole message as text" in
716 Mail::Message::Construct::Text
717 $obj->lines()
719 Inherited, see "The whole message as text" in
720 Mail::Message::Construct::Text
721 $obj->printStructure( [$fh|undef],[$indent] )
723 Inherited, see "The whole message as text" in
724 Mail::Message::Construct::Text
725 $obj->string()
727 Inherited, see "The whole message as text" in
728 Mail::Message::Construct::Text
729 Internals
731 $obj->clonedFrom()
732 Returns the $message which is the source of this message, which was
733 created by a clone() operation.
734 Mail::Message->coerce($message, %options)
736 Coerce a $message into a Mail::Message. In some occasions, for
737 instance where you add a message to a folder, this coercion is
738 automatically called to ensure that the correct message type is
739 stored.
740 The coerced message is returned on success, otherwise "undef". The
742 coerced message may be a reblessed version of the original message
743 or a new object. In case the message has to be specialized, for
744 instance from a general Mail::Message into a
745 Mail::Box::Mbox::Message, no copy is needed. However, to coerce a
746 Mail::Internet object into a Mail::Message, a lot of copying and
747 converting will take place.
748 Valid MESSAGEs which can be coerced into Mail::Message objects are
750 of type
751 • Any type of Mail::Box::Message
753 • MIME::Entity objects, using Mail::Message::Convert::MimeEntity
755 • Mail::Internet objects, using
757 Mail::Message::Convert::MailInternet
758 • Email::Simple objects, using
760 Mail::Message::Convert::EmailSimple
761 • Email::Abstract objects
763 Mail::Message::Part's, which are extensions of "Mail::Message"'s,
765 can also be coerced directly from a Mail::Message::Body.
766 example:
768 my $folder = Mail::Box::Mbox->new;
770 my $message = Mail::Message->build(...);
771 my $coerced = Mail::Box::Mbox::Message->coerce($message);
773 $folder->addMessage($coerced);
774 Simpler replacement for the previous two lines:
776 my $coerced = $folder->addMessage($message);
778 $obj->isDelayed()
780 Check whether the message is delayed (not yet read from file).
781 Returns true or false, dependent on the body type.
782 $obj->readBody( $parser, $head, [$bodytype] )
784 Read a body of a message. The $parser is the access to the
785 folder's file, and the $head is already read. Information from the
786 $head is used to create expectations about the message's length,
787 but also to determine the mime-type and encodings of the body data.
788 The $bodytype determines which kind of body will be made and
790 defaults to the value specified by new(body_type). $bodytype may
791 be the name of a body class, or a reference to a routine which
792 returns the body's class when passed the $head as only argument.
793 $obj->readFromParser( $parser, [$bodytype] )
795 Read one message from file. The $parser is opened on the file.
796 First readHead() is called, and the head is stored in the message.
797 Then readBody() is called, to produce a body. Also the body is
798 added to the message without decodings being done.
799 The optional $bodytype may be a body class or a reference to a code
801 which returns a body-class based on the header.
802 $obj->readHead( $parser, [$class] )
804 Read a head into an object of the specified $class. The $class
805 defaults to new(head_type). The $parser is the access to the
806 folder's file.
807 $obj->recursiveRebuildPart($part, %options)
809 Inherited, see "Internals" in Mail::Message::Construct::Rebuild
810 $obj->storeBody($body)
812 Where the body() method can be used to set and get a body, with all
813 the necessary checks, this method is bluntly adding the specified
814 body to the message. No conversions, not checking.
815 $obj->takeMessageId( [STRING] )
817 Take the message-id from the STRING, or create one when the "undef"
818 is specified. If not STRING nor "undef" is given, the current
819 header of the message is requested for the value of the
820 'Message-ID' field.
821 Angles (if present) are removed from the id.
823 Error handling
825 Extends "Error handling" in Mail::Reporter.
826 $obj->AUTOLOAD()
828 Inherited, see "METHODS" in Mail::Message::Construct
829 $obj->addReport($object)
831 Inherited, see "Error handling" in Mail::Reporter
832 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
834 $callback] )
835 Mail::Message->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
836 $callback] )
837 Inherited, see "Error handling" in Mail::Reporter
838 $obj->errors()
840 Inherited, see "Error handling" in Mail::Reporter
841 $obj->log( [$level, [$strings]] )
843 Mail::Message->log( [$level, [$strings]] )
844 Inherited, see "Error handling" in Mail::Reporter
845 $obj->logPriority($level)
847 Mail::Message->logPriority($level)
848 Inherited, see "Error handling" in Mail::Reporter
849 $obj->logSettings()
851 Inherited, see "Error handling" in Mail::Reporter
852 $obj->notImplemented()
854 Inherited, see "Error handling" in Mail::Reporter
855 $obj->report( [$level] )
857 Inherited, see "Error handling" in Mail::Reporter
858 $obj->reportAll( [$level] )
860 Inherited, see "Error handling" in Mail::Reporter
861 $obj->shortSize( [$value] )
863 Mail::Message->shortSize( [$value] )
864 Represent an integer $value representing the size of file or
865 memory, (which can be large) into a short string using M and K
866 (Megabytes and Kilobytes). Without $value, the size of the message
867 head is used.
868 $obj->shortString()
870 Convert the message header to a short string (without trailing
871 newline), representing the most important facts (for debugging
872 purposes only). For now, it only reports size and subject.
873 $obj->trace( [$level] )
875 Inherited, see "Error handling" in Mail::Reporter
876 $obj->warnings()
878 Inherited, see "Error handling" in Mail::Reporter
879 Cleanup
881 Extends "Cleanup" in Mail::Reporter.
882 $obj->DESTROY()
884 Inherited, see "Cleanup" in Mail::Reporter
885 $obj->destruct()
887 Remove the information contained in the message object. This will
888 be ignored when more than one reference to the same message object
889 exists, because the method has the same effect as assigning "undef"
890 to the variable which contains the reference. Normal garbage
891 collection will call "DESTROY()" when possible.
892 This method is only provided to hide differences with messages
894 which are located in folders: their Mail::Box::Message::destruct()
895 works quite differently.
896 example: of Mail::Message destruct
898 my $msg = Mail::Message->read;
900 $msg->destruct;
901 $msg = undef; # same
902
904 Structure of a Message
905 A MIME-compliant message is build upon two parts: the header and the
906 body.
907 The header
909 The header is a list of fields, some spanning more than one line
911 (folded) each telling something about the message. Information stored
912 in here are for instance the sender of the message, the receivers of
913 the message, when it was transported, how it was transported, etc.
914 Headers can grow quite large.
915 In MailBox, each message object manages exactly one header object (a
917 Mail::Message::Head) and one body object (a Mail::Message::Body). The
918 header contains a list of header fields, which are represented by
919 Mail::Message::Field objects.
920 The body
922 The body contains the "payload": the data to be transferred. The data
924 can be encoded, only accessible with a specific application, and may
925 use some weird character-set, like Vietnamese; the MailBox distribution
926 tries to assist you with handling these e-mails without the need to
927 know all the details. This additional information ("meta-information")
928 about the body data is stored in the header. The header contains more
929 information, for instance about the message transport and relations to
930 other messages.
931 Message object implementation
933 The general idea about the structure of a message is
934 Mail::Message
936 | |
937 | `-has-one--Mail::Message::Body
938 |
939 `----has-one--Mail::Message::Head
940 |
941 `-has-many--Mail::Message::Field
942 However: there are about 7 kinds of body objects, 3 kinds of headers
944 and 3 kinds of fields. You will usually not see too much of these
945 kinds, because they are merely created for performance reasons and can
946 be used all the same, with the exception of the multipart bodies.
947 A multipart body is either a Mail::Message::Body::Multipart (mime type
949 "multipart/*") or a Mail::Message::Body::Nested (mime type
950 "message/rfc822"). These bodies are more complex:
951 Mail::Message::Body::Multipart
953 |
954 `-has-many--Mail::Message::Part
955 | |
956 | `-has-one--Mail::Message::Body
957 |
958 `----has-one--Mail::Message::Head
959 Before you try to reconstruct multiparts or nested messages yourself,
961 you can better take a look at Mail::Message::Construct::Rebuild.
962 Message class implementation
964 The class structure of messages is very close to that of folders. For
965 instance, a Mail::Box::File::Message relates to a Mail::Box::File
966 folder.
967 As extra level of inheritance, it has a Mail::Message, which is a
969 message without location. And there is a special case of message:
970 Mail::Message::Part is a message encapsulated in a multipart body.
971 The message types are:
973 Mail::Box::Mbox::Message Mail::Box::POP3::Message
975 | Mail::Box::Dbx::Message Mail::Box::IMAP4::Message |
976 | | | |
977 Mail::Box::File::Message Mail::Box::Net::Message
978 | |
979 | Mail::Box::Maildir::Message |
980 | | Mail::Box::MH::Message |
981 | | | |
982 | Mail::Box::Dir::Message |
983 | | |
984 `------------. | .-----------------'
985 | | |
986 Mail::Box::Message Mail::Message::Part
987 | |
988 | .-------------'
989 | |
990 Mail::Message
991 |
992 |
993 Mail::Reporter (general base class)
994 By far most folder features are implemented in Mail::Box, so available
996 to all folder types. Sometimes, features which appear in only some of
997 the folder types are simulated for folders that miss them, like sub-
998 folder support for MBOX.
999 Two strange other message types are defined: the Mail::Message::Dummy,
1001 which fills holes in Mail::Box::Thread::Node lists, and a
1002 Mail::Box::Message::Destructed, this is an on purpose demolished
1003 message to reduce memory consumption.
1004 Labels
1006 Labels (also named "Flags") are used to indicate some special condition
1007 on the message, primary targeted on organizational issues: which
1008 messages are already read or should be deleted. There is a very strong
1009 user relation to labels.
1010 The main complication is that each folder type has its own way of
1012 storing labels. To give an indication: MBOX folders use "Status" and
1013 "X-Status" header fields, MH uses a ".mh-sequences" file, MAILDIR
1014 encodes the flags in the message's filename, and IMAP has flags as part
1015 of the protocol.
1016 Besides, some folder types can store labels with user defined names,
1018 where other lack that feature. Some folders have case-insensitive
1019 labels, other don't. Read all about the specifics in the manual page of
1020 the message type you actually have.
1021 Predefined labels
1023 To standardize the folder types, MailBox has defined the following
1025 labels, which can be used with the label() and labels() methods on all
1026 kinds of messages:
1027 • deleted
1029 This message is flagged to be deleted once the folder closes. Be
1031 very careful about the concept of 'delete' in a folder context : it
1032 is only a flag, and does not involve immediate action! This means,
1033 for instance, that the memory which is used by Perl to store the
1034 message is not released immediately (see destruct() if you need
1035 to).
1036 The methods delete(), deleted(), and isDeleted() are only short-
1038 cuts for managing the "delete" label (as of MailBox 2.052).
1039 • draft
1041 The user has prepared this message, but is has not been send (yet).
1043 This flag is not automatically added to a message by MailBox, and
1044 has only a meaning in user applications.
1045 • flagged
1047 Messages can be flagged for some purpose, for instance as result of
1049 a search for spam in a folder. The Mail::Box::messages() method
1050 can be used to collect all these flagged messages from the folder.
1051 Probably it is more useful to use an understandable name (like
1053 "spam") for these selections, however these self-defined labels can
1054 not stored in all folder types.
1055 • old
1057 The message was already in the folder when it was opened the last
1059 time, so was not recently added to the folder. This flag will
1060 never automatically be set by MailBox, because it would probably
1061 conflict with the user's idea of what is old.
1062 • passed
1064 Not often used or kept, this flag indicates that the message was
1066 bounced or forwarded to someone else.
1067 • replied
1069 The user (or application) has sent a message back to the sender of
1071 the message, as response of this one. This flag is automatically
1072 set if you use reply(), but not with forward() or bounce().
1073 • seen
1075 When this flag is set, the receiver of the message has consumed the
1077 message. A mail user agent (MUA) will set this flag when the user
1078 has opened the message once.
1079 Status and X-Status fields
1081 Mbox folders have no special means of storing information about
1083 messages (except the message separator line), and therefore have to
1084 revert to adding fields to the message header when something special
1085 comes up. This feature is also enabled for POP3, although whether that
1086 works depends on the POP server.
1087 All applications which can handle mbox folders support the "Status" and
1089 "X-Status" field convensions. The following encoding is used:
1090 Flag Field Label
1092 R Status => seen (Read)
1093 O Status => old (not recent)
1094 A X-Status => replied (Answered)
1095 F X-Status => flagged
1096 There is no special flag for "deleted", which most other folders
1098 support: messages flagged to be deleted will never be written to a
1099 folder file when it is closed.
1100
1102 Error: Cannot coerce a $class object into a $class object
1103 Error: Cannot include forward source as $include.
1104 Unknown alternative for the forward(include). Valid choices are
1105 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
1106 Error: Cannot include reply source as $include.
1108 Unknown alternative for the "include" option of reply(). Valid
1109 choices are "NO", "INLINE", and "ATTACH".
1110 Error: Method bounce requires To, Cc, or Bcc
1112 The message bounce() method forwards a received message off to
1113 someone else without modification; you must specified it's new
1114 destination. If you have the urge not to specify any destination,
1115 you probably are looking for reply(). When you wish to modify the
1116 content, use forward().
1117 Error: Method forwardAttach requires a preamble
1119 Error: Method forwardEncapsulate requires a preamble
1120 Error: No address to create forwarded to.
1121 If a forward message is created, a destination address must be
1122 specified.
1123 Error: No default mailer found to send message.
1125 The message send() mechanism had not enough information to
1126 automatically find a mail transfer agent to sent this message.
1127 Specify a mailer explicitly using the "via" options.
1128 Error: No rebuild rule $name defined.
1130 Error: Only build() Mail::Message's; they are not in a folder yet
1131 You may wish to construct a message to be stored in a some kind of
1132 folder, but you need to do that in two steps. First, create a
1133 normal Mail::Message, and then add it to the folder. During this
1134 Mail::Box::addMessage() process, the message will get coerce()-d
1135 into the right message type, adding storage information and the
1136 like.
1137 Error: Package $package does not implement $method.
1139 Fatal error: the specific package (or one of its superclasses) does
1140 not implement this method where it should. This message means that
1141 some other related classes do implement this method however the
1142 class at hand does not. Probably you should investigate this and
1143 probably inform the author of the package.
1144 Error: coercion starts with some object
1146
1148 This module is part of Mail-Message distribution version 3.012, built
1149 on February 11, 2022. Website: http://perl.overmeer.net/CPAN/
1150
1152 Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
1153 contributors see ChangeLog.
1154 This program is free software; you can redistribute it and/or modify it
1156 under the same terms as Perl itself. See http://dev.perl.org/licenses/
1157perl v5.34.0 2022-03-01 Mail::Message(3)