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 $msg = Mail::Message->build(...);
38 my $reply_msg = Mail::Message->reply(...);
39 my $frwd_msg = Mail::Message->forward(...);
40 my Mail::Message::Head $head = $msg->head;
42 my Mail::Message::Body $body = $msg->decoded;
43 $msg->decoded->print($outfile);
44
46 A "Mail::Message" object is a container for MIME-encoded message
47 information, as defined by RFC2822. Everything what is not specificly
48 related to storing the messages in mailboxes (folders) is implemented
49 in this class. Methods which are related to folders is implemented in
50 the Mail::Box::Message extension.
51 The main methods are get(), to get information from a message header
53 field, and decoded() to get the intended content of a message. But
54 there are many more which can assist your program.
55 Complex message handling, like construction of replies and forwards,
57 are implemented in separate packages which are autoloaded into this
58 class. This means you can simply use these methods as if they are part
59 of this class. Those package add functionality to all kinds of message
60 objects.
61
63 Constructors
64 $obj->clone(OPTIONS)
65 Create a copy of this message. Returned is a "Mail::Message"
66 object. The head and body, the log and trace levels are taken.
67 Labels are copied with the message, but the delete and modified
68 flags are not.
69 BE WARNED: the clone of any kind of message (or a message part)
71 will always be a "Mail::Message" object. For example, a
72 Mail::Box::Message's clone is detached from the folder of its
73 original. When you use Mail::Box::addMessage() with the cloned
74 message at hand, then the clone will automatically be coerced into
75 the right message type to be added.
76 See also Mail::Box::Message::copyTo() and
78 Mail::Box::Message::moveTo().
79 -Option --Default
81 shallow <false>
82 shallow_body <false>
83 shallow_head <false>
84 shallow => BOOLEAN
86 When a shallow clone is made, the header and body of the message
87 will not be cloned, but shared. This is quite dangerous: for
88 instance in some folder types, the header fields are used to
89 store folder flags. When one of both shallow clones change the
90 flags, that will update the header and thereby be visible in
91 both.
92 There are situations where a shallow clone can be used safely.
94 For instance, when Mail::Box::Message::moveTo() is used and you
95 are sure that the original message cannot get undeleted after the
96 move.
97 shallow_body => BOOLEAN
99 A rather safe bet, because you are not allowed to modify the body
100 of a message: you may only set a new body with body().
101 shallow_head => BOOLEAN
103 Only the head uses is reused, not the body. This is probably a
104 bad choice, because the header fields can be updated, for
105 instance when labels change.
106 example:
108 $copy = $msg->clone;
110 Mail::Message->new(OPTIONS)
112 -Option --Defined in --Default
113 body undef
114 body_type Mail::Message::Body::Lines
115 deleted <false>
116 field_type undef
117 head undef
118 head_type Mail::Message::Head::Complete
119 labels {}
120 log Mail::Reporter 'WARNINGS'
121 messageId undef
122 modified <false>
123 trace Mail::Reporter 'WARNINGS'
124 trusted <false>
125 body => OBJECT
127 Instantiate the message with a body which has been created
128 somewhere before the message is constructed. The OBJECT must be
129 a sub-class of Mail::Message::Body. See also body() and
130 storeBody().
131 body_type => CLASS
133 Default type of body to be created for readBody().
134 deleted => BOOLEAN
136 Is the file deleted from the start?
137 field_type => CLASS
139 head => OBJECT
140 Instantiate the message with a head which has been created
141 somewhere before the message is constructed. The OBJECT must be
142 a (sub-)class of Mail::Message::Head. See also head().
143 head_type => CLASS
145 Default type of head to be created for readHead().
146 labels => ARRAY|HASH
148 Initial values of the labels. In case of Mail::Box::Message's,
149 this shall reflect the state the message is in. For newly
150 constructed Mail::Message's, this may be anything you want,
151 because coerce() will take care of the folder specifics once the
152 message is added to one.
153 log => LEVEL
155 messageId => STRING
156 The id on which this message can be recognized. If none
157 specified and not defined in the header --but one is needed--
158 there will be one assigned to the message to be able to pass
159 unique message-ids between objects.
160 modified => BOOLEAN
162 Flags this message as being modified from the beginning on.
163 Usually, modification is auto-detected, but there may be reasons
164 to be extra explicit.
165 trace => LEVEL
167 trusted => BOOLEAN
168 Is this message from a trusted source? If not, the content must
169 be checked before use. This checking will be performed when the
170 body data is decoded or used for transmission.
171 Constructing a message
173 $obj->bounce([RG-OBJECT|OPTIONS])
174 See "Constructing a message" in Mail::Message::Construct::Bounce
175 Mail::Message->build([MESSAGE|PART|BODY], CONTENT)
177 See "Constructing a message" in Mail::Message::Construct::Build
178 Mail::Message->buildFromBody(BODY, [HEAD], HEADERS)
180 See "Constructing a message" in Mail::Message::Construct::Build
181 $obj->forward(OPTIONS)
183 See "Constructing a message" in Mail::Message::Construct::Forward
184 $obj->forwardAttach(OPTIONS)
186 See "Constructing a message" in Mail::Message::Construct::Forward
187 $obj->forwardEncapsulate(OPTIONS)
189 See "Constructing a message" in Mail::Message::Construct::Forward
190 $obj->forwardInline(OPTIONS)
192 See "Constructing a message" in Mail::Message::Construct::Forward
193 $obj->forwardNo(OPTIONS)
195 See "Constructing a message" in Mail::Message::Construct::Forward
196 $obj->forwardPostlude
198 See "Constructing a message" in Mail::Message::Construct::Forward
199 $obj->forwardPrelude
201 See "Constructing a message" in Mail::Message::Construct::Forward
202 $obj->forwardSubject(STRING)
204 See "Constructing a message" in Mail::Message::Construct::Forward
205 Mail::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
207 OPTIONS)
208 See "Constructing a message" in Mail::Message::Construct::Read
209 $obj->rebuild(OPTIONS)
211 See "Constructing a message" in Mail::Message::Construct::Rebuild
212 $obj->reply(OPTIONS)
214 See "Constructing a message" in Mail::Message::Construct::Reply
215 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
217 See "Constructing a message" in Mail::Message::Construct::Reply
218 $obj->replySubject(STRING)
220 Mail::Message->replySubject(STRING)
221 See "Constructing a message" in Mail::Message::Construct::Reply
223 The message
225 $obj->container
226 If the message is a part of another message, "container" returns
227 the reference to the containing body.
228 example:
230 my Mail::Message $msg = ...
232 return unless $msg->body->isMultipart;
233 my $part = $msg->body->part(2);
234 return unless $part->body->isMultipart;
236 my $nested = $part->body->part(3);
237 $nested->container; # returns $msg->body
239 $nested->toplevel; # returns $msg
240 $msg->container; # returns undef
241 $msg->toplevel; # returns $msg
242 $msg->isPart; # returns false
243 $part->isPart; # returns true
244 $obj->isDummy
246 Dummy messages are used to fill holes in linked-list and such,
247 where only a message-id is known, but not the place of the header
248 of body data.
249 This method is also available for Mail::Message::Dummy objects,
251 where this will return "true". On any extension of
252 "Mail::Message", this will return "false".
253 $obj->isPart
255 Returns true if the message is a part of another message. This is
256 the case for Mail::Message::Part extensions of "Mail::Message".
257 $obj->messageId
259 Retrieve the message's id. Every message has a unique message-id.
260 This id is used mainly for recognizing discussion threads.
261 $obj->print([FILEHANDLE])
263 Print the message to the FILE-HANDLE, which defaults to the
264 selected filehandle, without the encapsulation sometimes required
265 by a folder type, like write() does.
266 example:
268 $message->print(\*STDERR); # to the error output
270 $message->print; # to the selected file
271 my $out = IO::File->new('out', 'w');
273 $message->print($out); # no encapsulation: no folder
274 $message->write($out); # with encapsulation: is folder.
275 $obj->send([MAILER], OPTIONS)
277 Transmit the message to anything outside this Perl program. MAILER
278 is a Mail::Transport::Send object. When the MAILER is not
279 specified, one will be created, and kept as default for the next
280 messages as well.
281 The OPTIONS are mailer specific, and a mixture of what is usable
283 for the creation of the mailer object and the sending itself.
284 Therefore, see for possible options Mail::Transport::Send::new()
285 and Mail::Transport::Send::send().
286 example:
288 $message->send;
290 is short (but little less flexibile) for
292 my $mailer = Mail::Transport::SMTP->new(@smtpopts);
294 $mailer->send($message, @sendopts);
295 See examples/send.pl in the distribution of Mail::Box.
297 example:
299 $message->send(via => 'sendmail')
301 $obj->size
303 Returns an estimated size of the whole message in bytes. In many
304 occasions, the functions which process the message further, for
305 instance send() or print() will need to add/change header lines or
306 add CR characters, so the size is only an estimate with a few
307 percent margin of the real result.
308 The computation assumes that each line ending is represented by one
310 character (like UNIX, MacOS, and sometimes Cygwin), and not two
311 characters (like Windows and sometimes Cygwin). If you write the
312 message to file on a system which uses CR and LF to end a single
313 line (all Windows versions), the result in that file will be at
314 least nrLines() larger than this method returns.
315 $obj->toplevel
317 Returns a reference to the main message, which will be the current
318 message if the message is not part of another message.
319 $obj->write([FILEHANDLE])
321 Write the message to the FILE-HANDLE, which defaults to the
322 selected FILEHANDLE, with all surrounding information which is
323 needed to put it correctly in a folder file.
324 In most cases, the result of "write" will be the same as with
326 print(). The main exception is for Mbox folder messages, which
327 will get printed with their leading 'From ' line and a trailing
328 blank. Each line of their body which starts with 'From ' will have
329 an '>' added in front.
330 The header
332 $obj->bcc
333 Returns the addresses which are specified on the "Bcc" header line
334 (or lines) A list of Mail::Address objects is returned. "Bcc"
335 stands for Blind Carbon Copy: destinations of the message which are
336 not listed in the messages actually sent. So, this field will be
337 empty for received messages, but may be present in messages you
338 construct yourself.
339 $obj->cc
341 Returns the addresses which are specified on the "Cc" header line
342 (or lines) A list of Mail::Address objects is returned. "Cc"
343 stands for Carbon Copy; the people addressed on this line receive
344 the message informational, and are usually not expected to reply on
345 its content.
346 $obj->date
348 Method has been removed for reasons of consistency. Use
349 timestamp() or "$msg->head->get('Date')".
350 $obj->destinations
352 Returns a list of Mail::Address objects which contains the combined
353 info of active "To", "Cc", and "Bcc" addresses. Double addresses
354 are removed if detectable.
355 $obj->from
357 Returns the addresses from the senders. It is possible to have
358 more than one address specified in the "From" field of the message,
359 according to the specification. Therefore a list of Mail::Address
360 objects is returned, which usually has length 1.
361 If you need only one address from a sender, for instance to create
363 a "original message by" line in constructed forwarded message body,
364 then use sender().
365 example: using from() to get all sender addresses
367 my @from = $message->from;
369 $obj->get(FIELDNAME)
371 Returns the value which is stored in the header field with the
372 specified name. The FIELDNAME is case insensitive. The unfolded
373 body of the field is returned, stripped from any attributes. See
374 Mail::Message::Field::body().
375 If the field has multiple appearances in the header, only the last
377 instance is returned. If you need more complex handing of fields,
378 then call Mail::Message::Head::get() yourself. See study() when
379 you want to be smart, doing the better (but slower) job.
380 example: the get() short-cut for header fields
382 print $msg->get('Content-Type'), "\n";
384 Is equivalent to:
386 print $msg->head->get('Content-Type')->body, "\n";
388 $obj->guessTimestamp
390 Return an estimate on the time this message was sent. The data is
391 derived from the header, where it can be derived from the "date"
392 and "received" lines. For MBox-like folders you may get the date
393 from the from-line as well.
394 This method may return "undef" if the header is not parsed or only
396 partially known. If you require a time, then use the timestamp()
397 method, described below.
398 example: using guessTimestamp() to get a transmission date
400 print "Receipt ", ($message->timestamp || 'unknown'), "\n";
402 $obj->head([HEAD])
404 Return (optionally after setting) the HEAD of this message. The
405 head must be an (sub-)class of Mail::Message::Head. When the head
406 is added, status information is taken from it and transformed into
407 labels. More labels can be added by the LABELS hash. They are
408 added later.
409 example:
411 my $header = Mail::Message::Head->new;
413 $msg->head($header); # set
414 my $head = $msg->head; # get
415 $obj->nrLines
417 Returns the number of lines used for the whole message.
418 $obj->sender
420 Returns exactly one address, which is the originator of this
421 message. The returned Mail::Address object is taken from the
422 "Sender" header field, unless that field does not exists, in which
423 case the first address from the "From" field is taken. If none of
424 both provide an address, "undef" is returned.
425 example: using sender() to get exactly one sender address
427 my $sender = $message->sender;
429 print "Reply to: ", $sender->format, "\n" if defined $sender;
430 $obj->study(FIELDNAME)
432 Study the content of a field, like get() does, with as main
433 difference that a Mail::Message::Field::Full object is returned.
434 These objects stringify to an utf8 decoded representation of the
435 data contained in the field, where get() does not decode. When the
436 field does not exist, then "undef" is returned. See
437 Mail::Message::Field::study().
438 example: the study() short-cut for header fields
440 print $msg->study('to'), "\n";
442 Is equivalent to:
444 print $msg->head->study('to'), "\n"; # and
446 print $msg->head->get('to')->study, "\n";
447 or better:
449 if(my $to = $msg->study('to')) { print "$to\n" }
450 if(my $to = $msg->get('to')) { print $to->study, "\n" }
451 $obj->subject
453 Returns the message's subject, or the empty string.
454 example: using subject() to get the message's subject
456 print $msg->subject;
458 $obj->timestamp
460 Get a good timestamp for the message, doesn't matter how much work
461 it is. The value returned is compatible with the platform
462 dependent result of function time().
463 In these days, the timestamp as supplied by the message (in the
465 "Date" field) is not trustable at all: many spammers produce
466 illegal or unreal dates to influence their location in the
467 displayed folder.
468 To start, the received headers are tried for a date (see
470 Mail::Message::Head::Complete::recvstamp()) and only then the
471 "Date" field. In very rare cases, only with some locally produced
472 messages, no stamp can be found.
473 $obj->to
475 Returns the addresses which are specified on the "To" header line
476 (or lines). A list of Mail::Address objects is returned. The
477 people addressed here are the targets of the content, and should
478 read it contents carefully.
479 example: using to() to get all primar destination addresses
481 my @to = $message->to;
483 The body
485 $obj->body([BODY])
486 Return the body of this message. BE WARNED that this returns you
487 an object which may be encoded: use decoded() to get a body with
488 usable data.
489 With options, a new BODY is set for this message. This is not for
491 normal use unless you understand the consequences: you change the
492 message content without changing the message-ID. The right way to
493 go is via
494 $message = Mail::Message->buildFromBody($body); # or
496 $message = Mail::Message->build($body); # or
497 $message = $origmsg->forward(body => $body);
498 The BODY must be an (sub-)class of Mail::Message::Body. In this
500 case, information from the specified body will be copied into the
501 header. The body object will be encoded if needed, because
502 messages written to file or transmitted shall not contain binary
503 data. The converted body is returned.
504 When BODY is "undef", the current message body will be dissected
506 from the message. All relation will be cut. The body is returned,
507 and can be connected to a different message.
508 example:
510 my $body = $msg->body;
512 my @encoded = $msg->body->lines;
513 my $new = Mail::Message::Body->new(mime_type => 'text/html');
515 my $converted = $msg->body($new);
516 $obj->contentType
518 Returns the content type header line, or "text/plain" if it is not
519 defined. The parameters will be stripped off.
520 $obj->decoded(OPTIONS)
522 Decodes the body of this message, and returns it as a body object.
523 If there was no encoding, the body object as read from file is
524 passed on, however, some more work will be needed when a serious
525 encoding is encountered. The OPTIONS control how the conversion
526 takes place.
527 -Option --Default
529 charset PERL
530 result_type <type of body>
531 charset => CODESET|'PERL'
533 Translate the bytes of the message into the CODESET. When "PERL"
534 is given, the content will be translated into Perl strings.
535 result_type => BODYTYPE
537 Specifies which kind of body should be used for the final result,
538 and eventual intermediate conversion stages. It is not sure that
539 this will be the type of the body returned. BODYTYPE extends
540 Mail::Message::Body.
541 example:
543 $message->decoded->print(\*OUT);
545 $message->decoded->print;
546 $obj->encode(OPTIONS)
548 Encode the message to a certain format. Read the details in the
549 dedicated manual page Mail::Message::Body::Encode. The OPTIONS
550 which can be specified here are those of the
551 Mail::Message::Body::encode() method.
552 $obj->isMultipart
554 Check whether this message is a multipart message (has
555 attachments). To find this out, we need at least the header of the
556 message; there is no need to read the body of the message to detect
557 this.
558 $obj->isNested
560 Returns "true" for "message/rfc822" messages and message parts.
561 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
563 Returns the parts of this message. Usually, the term part is used
564 with multipart messages: messages which are encapsulated in the
565 body of a message. To abstract this concept: this method will
566 return you all header-body combinations which are stored within
567 this message except the multipart and message/rfc822 wrappers.
568 Objects returned are "Mail::Message"'s and Mail::Message::Part's.
569 The option default to 'ALL', which will return the message itself
571 for single-parts, the nested content of a message/rfc822 object,
572 respectively the parts of a multipart without recursion. In case
573 of 'RECURSE', the parts of multiparts will be collected
574 recursively. This option cannot be combined with the other
575 options, which you may want: it that case you have to test
576 yourself.
577 'ACTIVE' and 'DELETED' check for the deleted flag on messages and
579 message parts. The FILTER is a code reference, which is called for
580 each part of the message; each part as "RECURSE" would return.
581 example:
583 my @parts = $msg->parts; # $msg not multipart: returns ($msg)
585 my $parts = $msg->parts('ACTIVE'); # returns ($msg)
586 $msg->delete;
588 my @parts = $msg->parts; # returns ($msg)
589 my $parts = $msg->parts('ACTIVE'); # returns ()
590 Flags
592 $obj->delete
593 Flag the message to be deleted, which is a shortcut for
594 $msg->label(deleted => time); The real deletion only takes place
595 on a synchronization of the folder. See deleted() as well.
596 The time stamp of the moment of deletion is stored as value, but
598 that is not always preserved in the folder (depends on the
599 implementation). When the same message is deleted more than once,
600 the first time stamp will stay.
601 example:
603 $message->delete;
605 $message->deleted(1); # exactly the same
606 $message->label(deleted => 1);
607 delete $message;
608 $obj->deleted([BOOLEAN])
610 Set the delete flag for this message. Without argument, the method
611 returns the same as isDeleted(), which is preferred. When a true
612 value is given, delete() is called.
613 example:
615 $message->deleted(1); # delete
617 $message->delete; # delete (preferred)
618 $message->deleted(0); # undelete
620 if($message->deleted) {...} # check
622 if($message->isDeleted) {...} # check (preferred)
623 $obj->isDeleted
625 Short-cut for
626 $msg->label('deleted')
627 For some folder types, you will get the time of deletion in return.
629 This depends on the implementation.
630 example:
632 next if $message->isDeleted;
634 if(my $when = $message->isDeleted) {
636 print scalar localtime $when;
637 }
638 $obj->isModified
640 Returns whether this message is flagged as being modified.
641 Modifications are changes in header lines, when a new body is set
642 to the message (dangerous), or when labels change.
643 $obj->label(LABEL|PAIRS)
645 Return the value of the LABEL, optionally after setting some
646 values. In case of setting values, you specify key-value PAIRS.
647 Labels are used to store knowledge about handling of the message
649 within the folder. Flags about whether a message was read, replied
650 to, or scheduled for deletion.
651 Some labels are taken from the header's "Status" and "X-Status"
653 lines. Folder types like MH define a separate label file, and
654 Maildir adds letters to the message filename. But the MailBox
655 labels are always the same.
656 example:
658 print $message->label('seen');
660 if($message->label('seen')) {...};
661 $message->label(seen => 1);
662 $message->label(deleted => 1); # same as $message->delete
664 $obj->labels
666 Returns all known labels. In SCALAR context, it returns the
667 knowledge as reference to a hash. This is a reference to the
668 original data, but you shall *not* change that data directly: call
669 "label" for changes!
670 In LIST context, you get a list of names which are defined. Be
672 warned that they will not all evaluate to true, although most of
673 them will.
674 $obj->labelsToStatus
676 When the labels were changed, that may effect the "Status" and/or
677 "X-Status" header lines of mbox messages. Read about the relation
678 between these fields and the labels in the DETAILS chapter.
679 The method will carefully only affect the result of modified() when
681 there is a real change of flags, so not for each call to label().
682 $obj->modified([BOOLEAN])
684 Returns (optionally after setting) whether this message is flagged
685 as being modified. See isModified().
686 $obj->statusToLabels
688 Update the labels according the status lines in the header. See
689 the description in the DETAILS chapter.
690 The whole message as text
692 $obj->file
693 See "The whole message as text" in Mail::Message::Construct::Text
694 $obj->lines
696 See "The whole message as text" in Mail::Message::Construct::Text
697 $obj->printStructure([FILEHANDLE|undef],[INDENT])
699 See "The whole message as text" in Mail::Message::Construct::Text
700 $obj->string
702 See "The whole message as text" in Mail::Message::Construct::Text
703 Internals
705 $obj->clonedFrom
706 Returns the MESSAGE which is the source of this message, which was
707 created by a clone() operation.
708 Mail::Message->coerce(MESSAGE, OPTIONS)
710 Coerce a MESSAGE into a Mail::Message. In some occasions, for
711 instance where you add a message to a folder, this coercion is
712 automatically called to ensure that the correct message type is
713 stored.
714 The coerced message is returned on success, otherwise "undef". The
716 coerced message may be a reblessed version of the original message
717 or a new object. In case the message has to be specialized, for
718 instance from a general Mail::Message into a
719 Mail::Box::Mbox::Message, no copy is needed. However, to coerce a
720 Mail::Internet object into a Mail::Message, a lot of copying and
721 converting will take place.
722 Valid MESSAGEs which can be coerced into Mail::Message objects are
724 of type
725 · Any type of Mail::Box::Message
727 · MIME::Entity objects, using Mail::Message::Convert::MimeEntity
729 · Mail::Internet objects, using
731 Mail::Message::Convert::MailInternet
732 · Email::Simple objects, using
734 Mail::Message::Convert::EmailSimple
735 · Email::Abstract objects
737 Mail::Message::Part's, which are extensions of "Mail::Message"'s,
739 can also be coerced directly from a Mail::Message::Body.
740 example:
742 my $folder = Mail::Box::Mbox->new;
744 my $message = Mail::Message->build(...);
745 my $coerced = Mail::Box::Mbox::Message->coerce($message);
747 $folder->addMessage($coerced);
748 Simpler replacement for the previous two lines:
750 my $coerced = $folder->addMessage($message);
752 $obj->isDelayed
754 Check whether the message is delayed (not yet read from file).
755 Returns true or false, dependent on the body type.
756 $obj->readBody(PARSER, HEAD [, BODYTYPE])
758 Read a body of a message. The PARSER is the access to the folder's
759 file, and the HEAD is already read. Information from the HEAD is
760 used to create expectations about the message's length, but also to
761 determine the mime-type and encodings of the body data.
762 The BODYTYPE determines which kind of body will be made and
764 defaults to the value specified by new(body_type). BODYTYPE may be
765 the name of a body class, or a reference to a routine which returns
766 the body's class when passed the HEAD as only argument.
767 $obj->readFromParser(PARSER, [BODYTYPE])
769 Read one message from file. The PARSER is opened on the file.
770 First readHead() is called, and the head is stored in the message.
771 Then readBody() is called, to produce a body. Also the body is
772 added to the message without decodings being done.
773 The optional BODYTYPE may be a body class or a reference to a code
775 which returns a body-class based on the header.
776 $obj->readHead(PARSER [,CLASS])
778 Read a head into an object of the specified CLASS. The CLASS
779 defaults to new(head_type). The PARSER is the access to the
780 folder's file.
781 $obj->recursiveRebuildPart(PART, OPTIONS)
783 See "Internals" in Mail::Message::Construct::Rebuild
784 $obj->storeBody(BODY)
786 Where the body() method can be used to set and get a body, with all
787 the necessary checks, this method is bluntly adding the specified
788 body to the message. No conversions, not checking.
789 $obj->takeMessageId([STRING])
791 Take the message-id from the STRING, or create one when the "undef"
792 is specified. If not STRING nor "undef" is given, the current
793 header of the message is requested for the value of the
794 'Message-ID' field.
795 Angles (if present) are removed from the id.
797 Error handling
799 $obj->AUTOLOAD
800 See "METHODS" in Mail::Message::Construct
801 $obj->addReport(OBJECT)
803 See "Error handling" in Mail::Reporter
804 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
806 Mail::Message->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
807 CALLBACK])
808 See "Error handling" in Mail::Reporter
810 $obj->errors
812 See "Error handling" in Mail::Reporter
813 $obj->log([LEVEL [,STRINGS]])
815 Mail::Message->log([LEVEL [,STRINGS]])
816 See "Error handling" in Mail::Reporter
818 $obj->logPriority(LEVEL)
820 Mail::Message->logPriority(LEVEL)
821 See "Error handling" in Mail::Reporter
823 $obj->logSettings
825 See "Error handling" in Mail::Reporter
826 $obj->notImplemented
828 See "Error handling" in Mail::Reporter
829 $obj->report([LEVEL])
831 See "Error handling" in Mail::Reporter
832 $obj->reportAll([LEVEL])
834 See "Error handling" in Mail::Reporter
835 $obj->shortSize([VALUE])
837 Mail::Message->shortSize([VALUE])
838 Represent an integer VALUE representing the size of file or memory,
840 (which can be large) into a short string using M and K (Megabytes
841 and Kilobytes). Without VALUE, the size of the message head is
842 used.
843 $obj->shortString
845 Convert the message header to a short string (without trailing
846 newline), representing the most important facts (for debugging
847 purposes only). For now, it only reports size and subject.
848 $obj->trace([LEVEL])
850 See "Error handling" in Mail::Reporter
851 $obj->warnings
853 See "Error handling" in Mail::Reporter
854 Cleanup
856 $obj->DESTROY
857 When a message is to accessible anymore by any user's reference,
858 Perl will call DESTROY for final clean-up. In this case, the head
859 and body are released, and de-registered for the folder. You shall
860 not call this yourself!
861 $obj->destruct
863 Remove the information contained in the message object. This will
864 be ignored when more than one reference to the same message object
865 exists, because the method has the same effect as assigning "undef"
866 to the variable which contains the reference. Normal garbage
867 collection will call DESTROY() when possible.
868 This method is only provided to hide differences with messages
870 which are located in folders: their Mail::Box::Message::destruct()
871 works quite differently.
872 example: of Mail::Message destruct
874 my $msg = Mail::Message->read;
876 $msg->destruct;
877 $msg = undef; # same
878 $obj->inGlobalDestruction
880 See "Cleanup" in Mail::Reporter
881
883 Structure of a Message
884 The header
885 The header is a list of fields, some spanning more than one line
887 (folded) each telling something about the message. Information stored
888 in here are for instance the sender of the message, the receivers of
889 the message, when it was transported, how it was transported, etc.
890 Headers can grow quite large.
891 In MailBox, each message object manages exactly one header object (a
893 Mail::Message::Head) and one body object (a Mail::Message::Body). The
894 header contains a list of header fields, which are represented by
895 Mail::Message::Field objects.
896 The body
898 The body contains the "payload": the data to be transfered. The data
900 can be encoded, only accessible with a specific application, and may
901 use some weird character-set, like Vietnamese; the MailBox distribution
902 tries to assist you with handling these e-mails without the need to
903 know all the details. This additional information ("meta-information")
904 about the body data is stored in the header. The header contains more
905 information, for instance about the message transport and relations to
906 other messages.
907 A MIME-compliant message is build upon two parts: the header and the
909 body.
910 Message object implementation
912 The general idea about the structure of a message is
913 Mail::Message
915 | |
916 | `-has-one--Mail::Message::Body
917 |
918 `----has-one--Mail::Message::Head
919 |
920 `-has-many--Mail::Message::Field
921 However: there are about 7 kinds of body objects, 3 kinds of headers
923 and 3 kinds of fields. You will usually not see too much of these
924 kinds, because they are merely created for performance reasons and can
925 be used all the same, with the exception of the multipart bodies.
926 A multipart body is either a Mail::Message::Body::Multipart (mime type
928 "multipart/*") or a Mail::Message::Body::Nested (mime type
929 "message/rfc822"). These bodies are more complex:
930 Mail::Message::Body::Multipart
932 |
933 `-has-many--Mail::Message::Part
934 | |
935 | `-has-one--Mail::Message::Body
936 |
937 `----has-one--Mail::Message::Head
938 Before you try to reconstruct multiparts or nested messages yourself,
940 you can better take a look at Mail::Message::Construct::Rebuild.
941 Message class implementation
943 The class structure of messages is very close to that of folders. For
944 instance, a Mail::Box::File::Message relates to a Mail::Box::File
945 folder.
946 As extra level of inheritance, it has a Mail::Message, which is a
948 message without location. And there is a special case of message:
949 Mail::Message::Part is a message encapsulated in a multipart body.
950 The message types are:
952 Mail::Box::Mbox::Message Mail::Box::POP3::Message
954 | Mail::Box::Dbx::Message Mail::Box::IMAP4::Message |
955 | | | |
956 Mail::Box::File::Message Mail::Box::Net::Message
957 | |
958 | Mail::Box::Maildir::Message |
959 | | Mail::Box::MH::Message |
960 | | | |
961 | Mail::Box::Dir::Message |
962 | | |
963 `------------. | .-----------------'
964 | | |
965 Mail::Box::Message Mail::Message::Part
966 | |
967 | .-------------'
968 | |
969 Mail::Message
970 |
971 |
972 Mail::Reporter (general base class)
973 By far most folder features are implemented in Mail::Box, so available
975 to all folder types. Sometimes, features which appear in only some of
976 the folder types are simulated for folders that miss them, like sub-
977 folder support for MBOX.
978 Two strange other message types are defined: the Mail::Message::Dummy,
980 which fills holes in Mail::Box::Thread::Node lists, and a
981 Mail::Box::Message::Destructed, this is an on purpose demolished
982 message to reduce memory consumption.
983 Labels
985 Predefined labels
986 To standardize the folder types, MailBox has defined the following
988 labels, which can be used with the label() and labels() methods on all
989 kinds of messages:
990 · deleted
992 This message is flagged to be deleted once the folder closes. Be
994 very careful about the concept of 'delete' in a folder context : it
995 is only a flag, and does not involve immediate action! This means,
996 for instance, that the memory which is used by Perl to store the
997 message is not released immediately (see destruct() if you need
998 to).
999 The methods delete(), deleted(), and isDeleted() are only short-
1001 cuts for managing the "delete" label (as of MailBox 2.052).
1002 · draft
1004 The user has prepared this message, but is has not been send (yet).
1006 This flag is not automatically added to a message by MailBox, and
1007 has only a meaning in user applications.
1008 · flagged
1010 Messages can be flagged for some purpose, for instance as result of
1012 a search for spam in a folder. The Mail::Box::messages() method
1013 can be used to collect all these flagged messages from the folder.
1014 Probably it is more useful to use an understandable name (like
1016 "spam") for these selections, however these self-defined labels can
1017 not stored in all folder types.
1018 · old
1020 The message was already in the folder when it was opened the last
1022 time, so was not recently added to the folder. This flag will
1023 never automatically be set by MailBox, because it would probably
1024 conflict with the user's idea of what is old.
1025 · passed
1027 Not often used or kept, this flag indicates that the message was
1029 bounced or forwarded to someone else.
1030 · replied
1032 The user (or application) has sent a message back to the sender of
1034 the message, as response of this one. This flag is automatically
1035 set if you use reply(), but not with forward() or bounce().
1036 · seen
1038 When this flag is set, the receiver of the message has consumed the
1040 message. A mail user agent (MUA) will set this flag when the user
1041 has opened the message once.
1042 Status and X-Status fields
1044 Mbox folders have no special means of storing information about
1046 messages (except the message separator line), and therefore have to
1047 revert to adding fields to the message header when something special
1048 comes up. This feature is also enabled for POP3, although whether that
1049 works depends on the POP server.
1050 All applications which can handle mbox folders support the "Status" and
1052 "X-Status" field convensions. The following encoding is used:
1053 Flag Field Label
1055 R Status => seen (Read)
1056 O Status => old (not recent)
1057 A X-Status => replied (Answered)
1058 F X-Status => flagged
1059 There is no special flag for "deleted", which most other folders
1061 support: messages flagged to be deleted will never be written to a
1062 folder file when it is closed.
1063 Labels (also named "Flags") are used to indicate some special condition
1065 on the message, primary targeted on organizational issues: which
1066 messages are already read or should be deleted. There is a very strong
1067 user relation to labels.
1068 The main complication is that each folder type has its own way of
1070 storing labels. To give an indication: MBOX folders use "Status" and
1071 "X-Status" header fields, MH uses a ".mh-sequences" file, MAILDIR
1072 encodes the flags in the message's filename, and IMAP has flags as part
1073 of the protocol.
1074 Besides, some folder types can store labels with user defined names,
1076 where other lack that feature. Some folders have case-insensitive
1077 labels, other don't. Read all about the specifics in the manual page of
1078 the message type you actually have.
1079
1081 Error: Cannot coerce a $class object into a $class object
1082 Error: Cannot include forward source as $include.
1083 Unknown alternative for the forward(include). Valid choices are
1084 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
1085 Error: Cannot include reply source as $include.
1087 Unknown alternative for the "include" option of reply(). Valid
1088 choices are "NO", "INLINE", and "ATTACH".
1089 Error: Method bounce requires To, Cc, or Bcc
1091 The message bounce() method forwards a received message off to
1092 someone else without modification; you must specified it's new
1093 destination. If you have the urge not to specify any destination,
1094 you probably are looking for reply(). When you wish to modify the
1095 content, use forward().
1096 Error: Method forwardAttach requires a preamble
1098 Error: Method forwardEncapsulate requires a preamble
1099 Error: No address to create forwarded to.
1100 If a forward message is created, a destination address must be
1101 specified.
1102 Error: No default mailer found to send message.
1104 The message send() mechanism had not enough information to
1105 automatically find a mail transfer agent to sent this message.
1106 Specify a mailer explicitly using the "via" options.
1107 Error: No rebuild rule $name defined.
1109 Error: Only build() Mail::Message's; they are not in a folder yet
1110 You may wish to construct a message to be stored in a some kind of
1111 folder, but you need to do that in two steps. First, create a
1112 normal Mail::Message, and then add it to the folder. During this
1113 Mail::Box::addMessage() process, the message will get coerce()-d
1114 into the right message type, adding storage information and the
1115 like.
1116 Error: Package $package does not implement $method.
1118 Fatal error: the specific package (or one of its superclasses) does
1119 not implement this method where it should. This message means that
1120 some other related classes do implement this method however the
1121 class at hand does not. Probably you should investigate this and
1122 probably inform the author of the package.
1123 Error: coercion starts with some object
1125
1127 This module is part of Mail-Box distribution version 2.097, built on
1128 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
1129
1131 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
1132 ChangeLog.
1133 This program is free software; you can redistribute it and/or modify it
1135 under the same terms as Perl itself. See
1136 http://www.perl.com/perl/misc/Artistic.html
1137perl v5.12.3 2011-01-26 Mail::Message(3)