Mail::Message(3pm)

1Mail::Message(3)      User Contributed Perl Documentation     Mail::Message(3)
2
3
4

NAME

6       Mail::Message - general message object
7

INHERITANCE

9        Mail::Message has extra code in
10          Mail::Message::Construct
11          Mail::Message::Construct::Rebuild
12          Mail::Message::Construct::Text
13          Mail::Message::Construct::Forward
14          Mail::Message::Construct::Bounce
15          Mail::Message::Construct::Read
16          Mail::Message::Construct::Build
17          Mail::Message::Construct::Reply
18
19        Mail::Message
20          is a Mail::Reporter
21
22        Mail::Message is extended by
23          Mail::Box::Message
24          Mail::Message::Dummy
25          Mail::Message::Part
26          Mail::Message::Replace::MailInternet
27

SYNOPSIS

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
34        my $subject = $msg->subject;         # The message's subject
35        my @cc      = $msg->cc;              # List of Mail::Address'es
36
37        my $msg       = Mail::Message->build(...);
38        my $reply_msg = Mail::Message->reply(...);
39        my $frwd_msg  = Mail::Message->forward(...);
40
41        my Mail::Message::Head $head = $msg->head;
42        my Mail::Message::Body $body = $msg->decoded;
43        $msg->decoded->print($outfile);
44

DESCRIPTION

46       A "Mail::Message" object is a container for MIME-encoded message infor‐
47       mation, 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
52       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
56       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

METHODS

63       Constructors
64
65       $obj->clone(OPTIONS)
66
67           Create a copy of this message.  Returned is a "Mail::Message"
68           object.  The head and body, the log and trace levels are taken.
69           Labels are copied with the message, but the delete and modified
70           flags are not.
71
72           BE WARNED: the clone of any kind of message (or a message part)
73           will always be a "Mail::Message" object.  For example, a
74           Mail::Box::Message's clone is detached from the folder of its orig‐
75           inal.  When you use Mail::Box::addMessage() with the cloned message
76           at hand, then the clone will automatically be coerced into the
77           right message type to be added.
78
79           See also Mail::Box::Message::copyTo() and Mail::Box::Mes‐
80           sage::moveTo().
81
82            Option      --Default
83            shallow       <false>
84            shallow_body  <false>
85            shallow_head  <false>
86
87           . shallow BOOLEAN
88
89               When a shallow clone is made, the header and body of the mes‐
90               sage will not be cloned, but shared.  This is quite dangerous:
91               for instance in some folder types, the header fields are used
92               to store folder flags.  When one of both shallow clones change
93               the flags, that will update the header and thereby be visible
94               in both.
95
96               There are situations where a shallow clone can be used safely.
97               For instance, when Mail::Box::Message::moveTo() is used and you
98               are sure that the original message cannot get undeleted after
99               the move.
100
101           . shallow_body BOOLEAN
102
103               A rather safe bet, because you are not allowed to modify the
104               body of a message: you may only set a new body with body().
105
106           . shallow_head BOOLEAN
107
108               Only the head uses is reused, not the body.  This is probably a
109               bad choice, because the header fields can be updated, for
110               instance when labels change.
111
112           Example:
113
114            $copy = $msg->clone;
115
116       Mail::Message->new(OPTIONS)
117
118        Option    --Defined in     --Default
119        body                         undef
120        body_type                    Mail::Message::Body::Lines
121        deleted                      <false>
122        field_type                   undef
123        head                         undef
124        head_type                    Mail::Message::Head::Complete
125        labels                       {}
126        log         Mail::Reporter   'WARNINGS'
127        messageId                    undef
128        modified                     <false>
129        trace       Mail::Reporter   'WARNINGS'
130        trusted                      <false>
131
132           . body OBJECT
133
134               Instantiate the message with a body which has been created
135               somewhere before the message is constructed.  The OBJECT must
136               be a sub-class of Mail::Message::Body.  See also body() and
137               storeBody().
138
139           . body_type CLASS
140
141               Default type of body to be created for readBody().
142
143           . deleted BOOLEAN
144
145               Is the file deleted from the start?
146
147           . field_type CLASS
148
149           . head OBJECT
150
151               Instantiate the message with a head which has been created
152               somewhere before the message is constructed.  The OBJECT must
153               be a (sub-)class of Mail::Message::Head. See also head().
154
155           . head_type CLASS
156
157               Default type of head to be created for readHead().
158
159           . labels ARRAY⎪HASH
160
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 con‐
163               structed Mail::Message's, this may be anything you want,
164               because coerce() will take care of the folder specifics once
165               the message is added to one.
166
167           . log LEVEL
168
169           . messageId STRING
170
171               The id on which this message can be recognized.  If none speci‐
172               fied and not defined in the header --but one is needed-- there
173               will be one assigned to the message to be able to pass unique
174               message-ids between objects.
175
176           . modified BOOLEAN
177
178               Flags this message as being modified from the beginning on.
179               Usually, modification is auto-detected, but there may be rea‐
180               sons to be extra explicit.
181
182           . trace LEVEL
183
184           . trusted BOOLEAN
185
186               Is this message from a trusted source?  If not, the content
187               must be checked before use.  This checking will be performed
188               when the body data is decoded or used for transmission.
189
190       Constructing a message
191
192       $obj->bounce([RG-OBJECT⎪OPTIONS])
193
194           See "Constructing a message" in Mail::Message::Construct::Bounce
195
196       Mail::Message->build([MESSAGE⎪PART⎪BODY], CONTENT)
197
198           See "Constructing a message" in Mail::Message::Construct::Build
199
200       Mail::Message->buildFromBody(BODY, [HEAD], HEADERS)
201
202           See "Constructing a message" in Mail::Message::Construct::Build
203
204       $obj->forward(OPTIONS)
205
206           See "Constructing a message" in Mail::Message::Construct::Forward
207
208       $obj->forwardAttach(OPTIONS)
209
210           See "Constructing a message" in Mail::Message::Construct::Forward
211
212       $obj->forwardEncapsulate(OPTIONS)
213
214           See "Constructing a message" in Mail::Message::Construct::Forward
215
216       $obj->forwardInline(OPTIONS)
217
218           See "Constructing a message" in Mail::Message::Construct::Forward
219
220       $obj->forwardNo(OPTIONS)
221
222           See "Constructing a message" in Mail::Message::Construct::Forward
223
224       $obj->forwardPostlude
225
226           See "Constructing a message" in Mail::Message::Construct::Forward
227
228       $obj->forwardPrelude
229
230           See "Constructing a message" in Mail::Message::Construct::Forward
231
232       $obj->forwardSubject(STRING)
233
234           See "Constructing a message" in Mail::Message::Construct::Forward
235
236       Mail::Message->read(FILEHANDLE⎪SCALAR⎪REF-SCALAR⎪ARRAY-OF-LINES,
237       OPTIONS)
238
239           See "Constructing a message" in Mail::Message::Construct::Read
240
241       $obj->rebuild(OPTIONS)
242
243           See "Constructing a message" in Mail::Message::Construct::Rebuild
244
245       $obj->reply(OPTIONS)
246
247           See "Constructing a message" in Mail::Message::Construct::Reply
248
249       $obj->replyPrelude([STRING⎪FIELD⎪ADDRESS⎪ARRAY-OF-THINGS])
250
251           See "Constructing a message" in Mail::Message::Construct::Reply
252
253       $obj->replySubject(STRING)
254
255       Mail::Message->replySubject(STRING)
256
257           See "Constructing a message" in Mail::Message::Construct::Reply
258
259       The message
260
261       $obj->container
262
263           If the message is a part of another message, "container" returns
264           the reference to the containing body.
265
266           Example:
267
268            my Mail::Message $msg = ...
269            return unless $msg->body->isMultipart;
270            my $part   = $msg->body->part(2);
271
272            return unless $part->body->isMultipart;
273            my $nested = $part->body->part(3);
274
275            $nested->container;  # returns $msg->body
276            $nested->toplevel;   # returns $msg
277            $msg->container;     # returns undef
278            $msg->toplevel;      # returns $msg
279            $msg->isPart;        # returns false
280            $part->isPart;       # returns true
281
282       $obj->isDummy
283
284           Dummy messages are used to fill holes in linked-list and such,
285           where only a message-id is known, but not the place of the header
286           of body data.
287
288           This method is also available for Mail::Message::Dummy objects,
289           where this will return "true".  On any extension of "Mail::Mes‐
290           sage", this will return "false".
291
292       $obj->isPart
293
294           Returns true if the message is a part of another message.  This is
295           the case for Mail::Message::Part extensions of "Mail::Message".
296
297       $obj->messageId
298
299           Retrieve the message's id.  Every message has a unique message-id.
300           This id is used mainly for recognizing discussion threads.
301
302       $obj->print([FILEHANDLE])
303
304           Print the message to the FILE-HANDLE, which defaults to the
305           selected filehandle, without the encapsulation sometimes required
306           by a folder type, like write() does.
307
308           Example:
309
310            $message->print(\*STDERR);  # to the error output
311            $message->print;            # to the selected file
312
313            my $out = IO::File->new('out', 'w');
314            $message->print($out);      # no encapsulation: no folder
315            $message->write($out);      # with encapsulation: is folder.
316
317       $obj->send([MAILER], OPTIONS)
318
319           Transmit the message to anything outside this Perl program.  MAILER
320           is a Mail::Transport::Send object.  When the MAILER is not speci‐
321           fied, one will be created, and kept as default for the next mes‐
322           sages as well.
323
324           The OPTIONS are mailer specific, and a mixture of what is usable
325           for the creation of the mailer object and the sending itself.
326           Therefore, see for possible options Mail::Transport::Send::new()
327           and Mail::Transport::Send::send().
328
329           Example:
330
331            $message->send;
332
333           is short (but little less flexibile) for
334
335            my $mailer = Mail::Transport::SMTP->new(@smtpopts);
336            $mailer->send($message, @sendopts);
337
338           See examples/send.pl in the distribution of Mail::Box.
339
340           Example:
341
342            $message->send(via => 'sendmail')
343
344       $obj->size
345
346           Returns an estimated size of the whole message in bytes.  In many
347           occasions, the functions which process the message further, for
348           instance send() or print() will need to add/change header lines or
349           add CR characters, so the size is only an estimate with a few per‐
350           cent margin of the real result.
351
352           The computation assumes that each line ending is represented by one
353           character (like UNIX, MacOS, and sometimes Cygwin), and not two
354           characters (like Windows and sometimes Cygwin).  If you write the
355           message to file on a system which uses CR and LF to end a single
356           line (all Windows versions), the result in that file will be at
357           least nrLines() larger than this method returns.
358
359       $obj->toplevel
360
361           Returns a reference to the main message, which will be the current
362           message if the message is not part of another message.
363
364       $obj->write([FILEHANDLE])
365
366           Write the message to the FILE-HANDLE, which defaults to the
367           selected FILEHANDLE, with all surrounding information which is
368           needed to put it correctly in a folder file.
369
370           In most cases, the result of "write" will be the same as with
371           print().  The main exception is for Mbox folder messages, which
372           will get printed with their leading 'From ' line and a trailing
373           blank.  Each line of their body which starts with 'From ' will have
374           an '>' added in front.
375
376       The header
377
378       $obj->bcc
379
380           Returns the addresses which are specified on the "Bcc" header line
381           (or lines) A list of Mail::Address objects is returned.  "Bcc"
382           stands for Blind Carbon Copy: destinations of the message which are
383           not listed in the messages actually sent.  So, this field will be
384           empty for received messages, but may be present in messages you
385           construct yourself.
386
387       $obj->cc
388
389           Returns the addresses which are specified on the "Cc" header line
390           (or lines) A list of Mail::Address objects is returned.  "Cc"
391           stands for Carbon Copy; the people addressed on this line receive
392           the message informational, and are usually not expected to reply on
393           its content.
394
395       $obj->date
396
397           Method has been removed for reasons of consistency.  Use time‐
398           stamp() or "$msg-"head->get('Date')>.
399
400       $obj->destinations
401
402           Returns a list of Mail::Address objects which contains the combined
403           info of active "To", "Cc", and "Bcc" addresses.  Double addresses
404           are removed if detectable.
405
406       $obj->from
407
408           Returns the addresses from the senders.  It is possible to have
409           more than one address specified in the "From" field of the message,
410           according to the specification. Therefore a list of Mail::Address
411           objects is returned, which usually has length 1.
412
413           If you need only one address from a sender, for instance to create
414           a "original message by" line in constructed forwarded message body,
415           then use sender().
416
417           Example: using from() to get all sender addresses
418
419            my @from = $message->from;
420
421       $obj->get(FIELDNAME)
422
423           Returns the value which is stored in the header field with the
424           specified name.  The FIELDNAME is case insensitive.  The unfolded
425           body of the field is returned, stripped from any attributes.  See
426           Mail::Message::Field::body().
427
428           If the field has multiple appearances in the header, only the last
429           instance is returned.  If you need more complex handing of fields,
430           then call Mail::Message::Head::get() yourself.  See study() when
431           you want to be smart, doing the better (but slower) job.
432
433           Example: the get() short-cut for header fields
434
435            print $msg->get('Content-Type'), "\n";
436
437           Is equivalent to:
438
439            print $msg->head->get('Content-Type')->body, "\n";
440
441       $obj->guessTimestamp
442
443           Return an estimate on the time this message was sent.  The data is
444           derived from the header, where it can be derived from the "date"
445           and "received" lines.  For MBox-like folders you may get the date
446           from the from-line as well.
447
448           This method may return "undef" if the header is not parsed or only
449           partially known.  If you require a time, then use the timestamp()
450           method, described below.
451
452           Example: using guessTimestamp() to get a transmission date
453
454            print "Receipt ", ($message->timestamp ⎪⎪ 'unknown'), "\n";
455
456       $obj->head([HEAD])
457
458           Return (optionally after setting) the HEAD of this message.  The
459           head must be an (sub-)class of Mail::Message::Head.  When the head
460           is added, status information is taken from it and transformed into
461           labels.  More labels can be added by the LABELS hash.  They are
462           added later.
463
464           Example:
465
466            $msg->head(Mail::Message::Head->new);  # set
467            my $head = $msg->head;                 # get
468
469       $obj->nrLines
470
471           Returns the number of lines used for the whole message.
472
473       $obj->sender
474
475           Returns exactly one address, which is the originator of this mes‐
476           sage.  The returned Mail::Address object is taken from the "Sender"
477           header field, unless that field does not exists, in which case the
478           first address from the "From" field is taken.  If none of both pro‐
479           vide an address, "undef" is returned.
480
481           Example: using sender() to get exactly one sender address
482
483            my $sender = $message->sender;
484            print "Reply to: ", $sender->format, "\n" if defined $sender;
485
486       $obj->study(FIELDNAME)
487
488           Study the content of a field, like get() does, with as main differ‐
489           ence that a Mail::Message::Field::Full object is returned.  These
490           objects stringify to an utf8 decoded representation of the data
491           contained in the field, where get() does not decode.  See
492           Mail::Message::Field::study().
493
494           Example: the study() short-cut for header fields
495
496            print $msg->study('to'), "\n";
497
498           Is equivalent to:
499
500            print $msg->head->study('to'), "\n";       # and
501            print $msg->head->get('to')->study, "\n";
502
503       $obj->subject
504
505           Returns the message's subject, or the empty string.
506
507           Example: using subject() to get the message's subject
508
509            print $msg->subject;
510
511       $obj->timestamp
512
513           Get a good timestamp for the message, doesn't matter how much work
514           it is.  The value returned is compatible with the platform depen‐
515           dent result of function time().
516
517           In these days, the timestamp as supplied by the message (in the
518           "Date" field) is not trustable at all: many spammers produce ille‐
519           gal or unreal dates to influence their location in the displayed
520           folder.
521
522           To start, the received headers are tried for a date (see Mail::Mes‐
523           sage::Head::Complete::recvstamp()) and only then the "Date" field.
524           In very rare cases, only with some locally produced messages, no
525           stamp can be found.
526
527       $obj->to
528
529           Returns the addresses which are specified on the "To" header line
530           (or lines).  A list of Mail::Address objects is returned.  The peo‐
531           ple addressed here are the targets of the content, and should read
532           it contents carefully.
533
534           Example: using to() to get all primar destination addresses
535
536            my @to = $message->to;
537
538       The body
539
540       $obj->body([BODY])
541
542           Return the body of this message.  BE WARNED that this returns you
543           an object which may be encoded: use decoded() to get a body with
544           usable data.
545
546           With options, a new BODY is set for this message.  This is not for
547           normal use unless you understand the consequences: you change the
548           message content without changing the message-ID.  The right way to
549           go is via
550
551            $message = Mail::Message->buildFromBody($body);  # or
552            $message = Mail::Message->build($body);          # or
553            $message = $origmsg->forward(body => $body);
554
555           The BODY must be an (sub-)class of Mail::Message::Body.  In this
556           case, information from the specified body will be copied into the
557           header.  The body object will be encoded if needed, because mes‐
558           sages written to file or transmitted shall not contain binary data.
559           The converted body is returned.
560
561           When BODY is "undef", the current message body will be dissected
562           from the message.  All relation will be cut.  The body is returned,
563           and can be connected to a different message.
564
565           Example:
566
567            my $body      = $msg->body;
568            my @encoded   = $msg->body->lines;
569
570            my $new       = Mail::Message::Body->new(mime_type => 'text/html');
571            my $converted = $msg->body($new);
572
573       $obj->decoded(OPTIONS)
574
575           Decodes the body of this message, and returns it as a body object.
576           If there was no encoding, the body object as read from file is
577           passed on, however, some more work will be needed when a serious
578           encoding is encountered.  The OPTIONS control how the conversion
579           takes place.
580
581            Option     --Default
582            keep         <false>
583            result_type  <type of body>
584
585           . keep BOOLEAN
586
587               Controls whether the decoded result will be kept.  If not, the
588               decoding may be performed more than once.  However, it will
589               consume extra resources...
590
591           . result_type BODYTYPE
592
593               Specifies which kind of body should be used for the final
594               result, and eventual intermediate conversion stages.  It is not
595               sure that this will be the type of the body returned.  BODYTYPE
596               extends Mail::Message::Body.
597
598           Example:
599
600            $message->decoded->print(\*OUT);
601            $message->decoded->print;
602
603            my $dec = $message->body($message->decoded);
604            my $dec = $message->decoded(keep => 1);   # same
605
606       $obj->encode(OPTIONS)
607
608           Encode the message to a certain format.  Read the details in the
609           dedicated manual page Mail::Message::Body::Encode.  The OPTIONS
610           which can be specified here are those of the Mail::Mes‐
611           sage::Body::encode() method.
612
613       $obj->isMultipart
614
615           Check whether this message is a multipart message (has attach‐
616           ments).  To find this out, we need at least the header of the mes‐
617           sage; there is no need to read the body of the message to detect
618           this.
619
620       $obj->isNested
621
622           Returns "true" for "message/rfc822" messages and message parts.
623
624       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
625
626           Returns the parts of this message. Usually, the term part is used
627           with multipart messages: messages which are encapsulated in the
628           body of a message.  To abstract this concept: this method will
629           return you all header-body combinations which are stored within
630           this message except the multipart and message/rfc822 wrappers.
631           Objects returned are "Mail::Message"'s and Mail::Message::Part's.
632
633           The option default to 'ALL', which will return the message itself
634           for single-parts, the nested content of a message/rfc822 object,
635           respectively the parts of a multipart without recursion.  In case
636           of 'RECURSE', the parts of multiparts will be collected recur‐
637           sively.  This option cannot be combined with the other options,
638           which you may want: it that case you have to test yourself.
639
640           'ACTIVE' and 'DELETED' check for the deleted flag on messages and
641           message parts.  The FILTER is a code reference, which is called for
642           each part of the messagei; each part as "RECURSE" would return.
643
644           Example:
645
646            my @parts = $msg->parts;           # $msg not multipart: returns ($msg)
647            my $parts = $msg->parts('ACTIVE'); # returns ($msg)
648
649            $msg->delete;
650            my @parts = $msg->parts;           # returns ($msg)
651            my $parts = $msg->parts('ACTIVE'); # returns ()
652
653       Flags
654
655       $obj->delete
656
657           Flag the message to be deleted, which is a shortcut for
658            $msg->label(deleted => time); The real deletion only takes place
659           on a synchronization of the folder.  See deleted() as well.
660
661           The time stamp of the moment of deletion is stored as value, but
662           that is not always preserved in the folder (depends on the imple‐
663           mentation).  When the same message is deleted more than once, the
664           first time stamp will stay.
665
666           Example:
667
668            $message->delete;
669            $message->deleted(1);  # exactly the same
670            $message->label(deleted => 1);
671            delete $message;
672
673       $obj->deleted([BOOLEAN])
674
675           Set the delete flag for this message.  Without argument, the method
676           returns the same as isDeleted(), which is prefered.  When a true
677           value is given, delete() is called.
678
679           Example:
680
681            $message->deleted(1);          # delete
682            $message->delete;              # delete (prefered)
683
684            $message->deleted(0);          # undelete
685
686            if($message->deleted) {...}    # check
687            if($message->isDeleted) {...}  # check (prefered)
688
689       $obj->isDeleted
690
691           Short-cut for
692            $msg->label('deleted')
693
694           For some folder types, you will get the time of deletion in return.
695           This depends on the implementation.
696
697           Example:
698
699            next if $message->isDeleted;
700
701            if(my $when = $message->isDeleted) {
702               print scalar localtime $when;
703            }
704
705       $obj->isModified
706
707           Returns whether this message is flagged as being modified.  Modifi‐
708           cations are changes in header lines, when a new body is set to the
709           message (dangerous), or when labels change.
710
711       $obj->label(LABEL⎪PAIRS)
712
713           Return the value of the LABEL, optionally after setting some val‐
714           ues.  In case of setting values, you specify key-value PAIRS.
715
716           Labels are used to store knowledge about handling of the message
717           within the folder.  Flags about whether a message was read, replied
718           to, or scheduled for deletion.
719
720           Some labels are taken from the header's "Status" and "X-Status"
721           lines, however folder types like MH define a separate label file.
722
723           Example:
724
725            print $message->label('seen');
726            if($message->label('seen')) {...};
727            $message->label(seen => 1);
728
729            $message->label(deleted => 1);  # same as $message->delete
730
731       $obj->labels
732
733           Returns all known labels.  In SCALAR context, it returns the knowl‐
734           edge as reference to a hash.  This is a reference to the original
735           data, but you shall *not* change that data directly: call "label"
736           for changes!
737
738           In LIST context, you get a list of names which are defined.  Be
739           warned that they will not all evaluate to true, although most of
740           them will.
741
742       $obj->labelsToStatus
743
744           When the labels were changed, that may effect the "Status" and/or
745           "X-Status" header lines of mbox messages.  Read about the relation
746           between these fields and the labels in the DETAILS chapter.
747
748           The method will carefully only affect the result of modified() when
749           there is a real change of flags, so not for each call to label().
750
751       $obj->modified([BOOLEAN])
752
753           Returns (optionally after setting) whether this message is flagged
754           as being modified.  See isModified().
755
756       $obj->statusToLabels
757
758           Update the labels according the status lines in the header.  See
759           the description in the DETAILS chapter.
760
761       The whole message as text
762
763       $obj->file
764
765           See "The whole message as text" in Mail::Message::Construct::Text
766
767       $obj->lines
768
769           See "The whole message as text" in Mail::Message::Construct::Text
770
771       $obj->printStructure([FILEHANDLE⎪undef],[INDENT])
772
773           See "The whole message as text" in Mail::Message::Construct::Text
774
775       $obj->string
776
777           See "The whole message as text" in Mail::Message::Construct::Text
778
779       Internals
780
781       $obj->clonedFrom
782
783           Returns the MESSAGE which is the source of this message, which was
784           created by a clone() operation.
785
786       Mail::Message->coerce(MESSAGE, OPTIONS)
787
788           Coerce a MESSAGE into a Mail::Message.  In some occasions, for
789           instance where you add a message to a folder, this coercion is
790           automatically called to ensure that the correct message type is
791           stored.
792
793           The coerced message is returned on success, otherwise "undef".  The
794           coerced message may be a reblessed version of the original message
795           or a new object.  In case the message has to be specialized, for
796           instance from a general Mail::Message into a Mail::Box::Mbox::Mes‐
797           sage, no copy is needed.  However, to coerce a Mail::Internet
798           object into a Mail::Message, a lot of copying and converting will
799           take place.
800
801           Valid MESSAGEs which can be coerced into Mail::Message objects are
802           of type
803
804           * Any type of Mail::Box::Message
805           * MIME::Entity's, using Mail::Message::Convert::MimeEntity
806           * Mail::Internet's, using Mail::Message::Convert::MailInternet
807
808           Mail::Message::Part's, which are extensions of "Mail::Message"'s,
809           can also be coerced directly from a Mail::Message::Body.
810
811           Example:
812
813            my $folder  = Mail::Box::Mbox->new;
814            my $message = Mail::Message->build(...);
815
816            my $coerced = Mail::Box::Mbox::Message->coerce($message);
817            $folder->addMessage($coerced);
818
819           Simpler replacement for the previous two lines:
820
821            my $coerced = $folder->addMessage($message);
822
823       $obj->isDelayed
824
825           Check whether the message is delayed (not yet read from file).
826           Returns true or false, dependent on the body type.
827
828       $obj->readBody(PARSER, HEAD [, BODYTYPE])
829
830           Read a body of a message.  The PARSER is the access to the folder's
831           file, and the HEAD is already read.  Information from the HEAD is
832           used to create expectations about the message's length, but also to
833           determine the mime-type and encodings of the body data.
834
835           The BODYTYPE determines which kind of body will be made and
836           defaults to the value specified by new(body_type).  BODYTYPE may be
837           the name of a body class, or a reference to a routine which returns
838           the body's class when passed the HEAD as only argument.
839
840       $obj->readFromParser(PARSER, [BODYTYPE])
841
842           Read one message from file.  The PARSER is opened on the file.
843           First readHead() is called, and the head is stored in the message.
844           Then readBody() is called, to produce a body.  Also the body is
845           added to the message without decodings being done.
846
847           The optional BODYTYPE may be a body class or a reference to a code
848           which returns a body-class based on the header.
849
850       $obj->readHead(PARSER [,CLASS])
851
852           Read a head into an object of the specified CLASS.  The CLASS
853           defaults to new(head_type).  The PARSER is the access to the
854           folder's file.
855
856       $obj->recursiveRebuildPart(PART, OPTIONS)
857
858           See "Internals" in Mail::Message::Construct::Rebuild
859
860       $obj->storeBody(BODY)
861
862           Where the body() method can be used to set and get a body, with all
863           the necessary checks, this method is bluntly adding the specified
864           body to the message.  No conversions, not checking.
865
866       $obj->takeMessageId([STRING])
867
868           Take the message-id from the STRING, or create one when the "undef"
869           is specified.  If not STRING nor "undef" is given, the current
870           header of the message is requested for the value of the 'Mes‐
871           sage-ID' field.
872
873           Angles (if present) are removed from the id.
874
875       Error handling
876
877       $obj->AUTOLOAD
878
879           See "METHODS" in Mail::Message::Construct
880
881       $obj->addReport(OBJECT)
882
883           See "Error handling" in Mail::Reporter
884
885       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
886
887       Mail::Message->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
888       CALLBACK])
889
890           See "Error handling" in Mail::Reporter
891
892       $obj->errors
893
894           See "Error handling" in Mail::Reporter
895
896       $obj->log([LEVEL [,STRINGS]])
897
898       Mail::Message->log([LEVEL [,STRINGS]])
899
900           See "Error handling" in Mail::Reporter
901
902       $obj->logPriority(LEVEL)
903
904       Mail::Message->logPriority(LEVEL)
905
906           See "Error handling" in Mail::Reporter
907
908       $obj->logSettings
909
910           See "Error handling" in Mail::Reporter
911
912       $obj->notImplemented
913
914           See "Error handling" in Mail::Reporter
915
916       $obj->report([LEVEL])
917
918           See "Error handling" in Mail::Reporter
919
920       $obj->reportAll([LEVEL])
921
922           See "Error handling" in Mail::Reporter
923
924       $obj->shortSize([VALUE])
925
926       Mail::Message->shortSize([VALUE])
927
928           Represent an integer VALUE representing the size of file or memory,
929           (which can be large) into a short string using M and K (Megabytes
930           and Kilobytes).  Without VALUE, the size of the message head is
931           used.
932
933       $obj->shortString
934
935           Convert the message header to a short string (without trailing new‐
936           line), representing the most important facts (for debugging pur‐
937           poses only).  For now, it only reports size and subject.
938
939       $obj->trace([LEVEL])
940
941           See "Error handling" in Mail::Reporter
942
943       $obj->warnings
944
945           See "Error handling" in Mail::Reporter
946
947       Cleanup
948
949       $obj->DESTROY
950
951           When a message is to accessible anymore by any user's reference,
952           Perl will call DESTROY for final clean-up.  In this case, the head
953           and body are released, and de-registered for the folder.  You shall
954           not call this yourself!
955
956       $obj->destruct
957
958           Remove the information contained in the message object.  This will
959           be ignored when more than one reference to the same message object
960           exists, because the method has the same effect as assigning "undef"
961           to the variable which contains the reference.  Normal garbage col‐
962           lection will call DESTROY() when possible.
963
964           This method is only provided to hide differences with messages
965           which are located in folders: their Mail::Box::Message::destruct()
966           works quite differently.
967
968           Example: of Mail::Message destruct
969
970            my $msg = Mail::Message->read;
971            $msg->destruct;
972            $msg = undef;    # same
973
974       $obj->inGlobalDestruction
975
976           See "Cleanup" in Mail::Reporter
977

DETAILS

979       Structure of a Message
980
981       A MIME-compliant message is build upon two parts: the header and the
982       body.
983
984       The header
985
986       The header is a list of fields, some spanning more than one line
987       (folded) each telling something about the message. Information stored
988       in here are for instance the sender of the message, the receivers of
989       the message, when it was transported, how it was transported, etc.
990       Headers can grow quite large.
991
992       In MailBox, each message object manages exactly one header object (a
993       Mail::Message::Head) and one body object (a Mail::Message::Body).  The
994       header contains a list of header fields, which are represented by
995       Mail::Message::Field objects.
996
997       The body
998
999       The body contains the "payload": the data to be transfered.  The data
1000       can be encoded, only accessible with a specific application, and may
1001       use some weird character-set, like Vietnamese; the MailBox distribution
1002       tries to assist you with handling these e-mails without the need to
1003       know all the details.  This additional information ("meta-information")
1004       about the body data is stored in the header.  The header contains more
1005       information, for instance about the message transport and relations to
1006       other messages.
1007
1008       Message object implementation
1009
1010       The general idea about the structure of a message is
1011
1012        Mail::Message
1013         ⎪  ⎪
1014         ⎪  `-has-one--Mail::Message::Body
1015         ⎪
1016         `----has-one--Mail::Message::Head
1017                         ⎪
1018                         `-has-many--Mail::Message::Field
1019
1020       However: there are about 7 kinds of body objects, 3 kinds of headers
1021       and 3 kinds of fields.  You will usually not see too much of these
1022       kinds, because they are merely created for performance reasons and can
1023       be used all the same, with the exception of the multipart bodies.
1024
1025       A multipart body is either a Mail::Message::Body::Multipart (mime type
1026       "multipart/*") or a Mail::Message::Body::Nested (mime type "mes‐
1027       sage/rfc822").  These bodies are more complex:
1028
1029        Mail::Message::Body::Multipart
1030         ⎪
1031         `-has-many--Mail::Message::Part
1032                      ⎪  ⎪
1033                      ⎪  `-has-one--Mail::Message::Body
1034                      ⎪
1035                      `----has-one--Mail::Message::Head
1036
1037       Before you try to reconstruct multiparts or nested messages yourself,
1038       you can better take a look at Mail::Message::Construct::Rebuild.
1039
1040       Message class implementation
1041
1042       The class structure of messages is very close to that of folders.  For
1043       instance, a Mail::Box::File::Message relates to a Mail::Box::File
1044       folder.
1045
1046       As extra level of inheritance, it has a Mail::Message, which is a mes‐
1047       sage without location.  And there is a special case of message:
1048       Mail::Message::Part is a message encapsulated in a multipart body.
1049
1050       The message types are:
1051
1052        Mail::Box::Mbox::Message            Mail::Box::POP3::Message
1053        ⎪  Mail::Box::Dbx::Message      Mail::Box::IMAP4::Message  ⎪
1054        ⎪  ⎪                                                    ⎪  ⎪
1055        Mail::Box::File::Message             Mail::Box::Net::Message
1056                ⎪                                      ⎪
1057                ⎪       Mail::Box::Maildir::Message    ⎪
1058                ⎪       ⎪   Mail::Box::MH::Message     ⎪
1059                ⎪       ⎪   ⎪                          ⎪
1060                ⎪       Mail::Box::Dir::Message        ⎪
1061                ⎪                ⎪                     ⎪
1062                `------------.   ⎪   .-----------------'
1063                             ⎪   ⎪   ⎪
1064                          Mail::Box::Message    Mail::Message::Part
1065                                 ⎪                     ⎪
1066                                 ⎪       .-------------'
1067                                 ⎪       ⎪
1068                             Mail::Message
1069                                 ⎪
1070                                 ⎪
1071                           Mail::Reporter (general base class)
1072
1073       By far most folder features are implemented in Mail::Box, so available
1074       to all folder types.  Sometimes, features which appear in only some of
1075       the folder types are simulated for folders that miss them, like sub-
1076       folder support for MBOX.
1077
1078       Two strange other message types are defined: the Mail::Message::Dummy,
1079       which fills holes in Mail::Box::Thread::Node lists, and a
1080       Mail::Box::Message::Destructed, this is an on purpose demolished mes‐
1081       sage to reduce memory consumption.
1082
1083       Labels
1084
1085       Labels (also named "Flags") are used to indicate some special condition
1086       on the message, primary targeted on organizational issues: which mes‐
1087       sages are already read or should be deleted.  There is a very strong
1088       user relation to labels.
1089
1090       The main complication is that each folder type has its own way of stor‐
1091       ing labels.  To give an indication: MBOX folders use "Status" and
1092       "X-Status" header fields, MH uses a ".mh-sequences" file, MAILDIR
1093       encodes the flags in the message's filename, and IMAP has flags as part
1094       of the protocol.
1095
1096       Besides, some folder types can store labels with user defined names,
1097       where other lack that feature.  Some folders have case-insensitive
1098       labels, other don't. Read all about the specifics in the manual page of
1099       the message type you actually have.
1100
1101       Predefined labels
1102
1103       To standardize the folder types, MailBox has defined the following
1104       labels, which can be used with the label() and labels() methods on all
1105       kinds of messages:
1106
1107       * deleted
1108           This message is flagged to be deleted once the folder closes.  Be
1109           very careful about the concept of 'delete' in a folder context : it
1110           is only a flag, and does not involve immediate action!  This means,
1111           for instance, that the memory which is used by Perl to store the
1112           message is not released immediately (see destruct() if you need
1113           to).
1114
1115           The methods delete(), deleted(), and isDeleted() are only short-
1116           cuts for managing the "delete" label (as of MailBox 2.052).
1117
1118       * draft
1119           The user has prepared this message, but is has not been send (yet).
1120           This flag is not automatically added to a message by MailBox, and
1121           has only a meaning in user applications.
1122
1123       * flagged
1124           Messages can be flagged for some purpose, for instance as result of
1125           a search for spam in a folder.  The Mail::Box::messages() method
1126           can be used to collect all these flagged messages from the folder.
1127
1128           Probably it is more useful to use an understandable name (like
1129           "spam") for these selections, however these self-defined labels can
1130           not stored in all folder types.
1131
1132       * old
1133           The message was already in the folder when it was opened the last
1134           time, so was not recently added to the folder.  This flag will
1135           never automatically be set by MailBox, because it would probably
1136           conflict with the user's idea of what is old.
1137
1138       * passed
1139           Not often used or kept, this flag indicates that the message was
1140           bounced or forwarded to someone else.
1141
1142       * replied
1143           The user (or application) has sent a message back to the sender of
1144           the message, as response of this one.  This flag is automatically
1145           set if you use reply(), but not with forward() or bounce().
1146
1147       * seen
1148           When this flag is set, the receiver of the message has consumed the
1149           message.  A mail user agent (MUA) will set this flag when the user
1150           has opened the message once.
1151
1152       Status and X-Status fields
1153
1154       Mbox folders have no special means of storing information about mes‐
1155       sages (except the message separator line), and therefore have to revert
1156       to adding fields to the message header when something special comes up.
1157       This feature is also enabled for POP3, although whether that works
1158       depends on the POP server.
1159
1160       All applications which can handle mbox folders support the "Status" and
1161       "X-Status" field convensions.  The following encoding is used:
1162
1163        Flag   Field       Label
1164        R      Status   => seen    (Read)
1165        O      Status   => old     (not recent)
1166        A      X-Status => replied (Answered)
1167        F      X-Status => flagged
1168
1169       There is no special flag for "deleted", which most other folders sup‐
1170       port: messages flagged to be deleted will never be written to a folder
1171       file when it is closed.
1172

DIAGNOSTICS

1174       Error: Cannot include forward source as $include.
1175
1176       Unknown alternative for the forward(include).  Valid choices are "NO",
1177       "INLINE", "ATTACH", and "ENCAPSULATE".
1178
1179       Error: Cannot include reply source as $include.
1180
1181       Unknown alternative for the "include" option of reply().  Valid choices
1182       are "NO", "INLINE", and "ATTACH".
1183
1184       Error: Method bounce requires To, Cc, or Bcc
1185
1186       The message bounce() method forwards a received message off to someone
1187       else without modification; you must specified it's new destination.  If
1188       you have the urge not to specify any destination, you probably are
1189       looking for reply(). When you wish to modify the content, use for‐
1190       ward().
1191
1192       Error: Method forwardAttach requires a preamble
1193
1194       Error: Method forwardEncapsulate requires a preamble
1195
1196       Error: No address to create forwarded to.
1197
1198       If a forward message is created, a destination address must be speci‐
1199       fied.
1200
1201       Error: No default mailer found to send message.
1202
1203       The message send() mechanism had not enough information to automati‐
1204       cally find a mail transfer agent to sent this message.  Specify a
1205       mailer explicitly using the "via" options.
1206
1207       Error: No rebuild rule $name defined.
1208
1209       Error: Only build() Mail::Message's; they are not in a folder yet
1210
1211       You may wish to construct a message to be stored in a some kind of
1212       folder, but you need to do that in two steps.  First, create a normal
1213       Mail::Message, and then add it to the folder.  During this
1214       Mail::Box::addMessage() process, the message will get coerce()-d into
1215       the right message type, adding storage information and the like.
1216
1217       Error: Package $package does not implement $method.
1218
1219       Fatal error: the specific package (or one of its superclasses) does not
1220       implement this method where it should. This message means that some
1221       other related classes do implement this method however the class at
1222       hand does not.  Probably you should investigate this and probably
1223       inform the author of the package.
1224

LICENSE

1230       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
1231       ChangeLog.
1232
1233       This program is free software; you can redistribute it and/or modify it
1234       under the same terms as Perl itself.  See
1235       http://www.perl.com/perl/misc/Artistic.html
1236
1237
1238
1239perl v5.8.8                       2007-03-25                  Mail::Message(3)