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::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
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 Mail::Message::Head $head = $msg->head;
38        my Mail::Message::Body $body = $msg->decoded;
39        $msg->decoded->print($outfile);
40
41        # Send a simple email
42        Mail::Message->build
43          ( To             => 'you@example.com'
44          , From           => 'me@example.com'
45          , Subject        => "My subject"
46          , data           => "Some plain text content"
47          )->send(via => 'postfix');
48
49        my $reply_msg = Mail::Message->reply(...);
50        my $frwd_msg  = Mail::Message->forward(...);
51

DESCRIPTION

53       A "Mail::Message" object is a container for MIME-encoded message
54       information, as defined by RFC2822.  Everything what is not specificaly
55       related to storing the messages in mailboxes (folders) is implemented
56       in this class.  Methods which are related to folders is implemented in
57       the Mail::Box::Message extension.
58
59       The main methods are get(), to get information from a message header
60       field, and decoded() to get the intended content of a message.  But
61       there are many more which can assist your program.
62
63       Complex message handling, like construction of replies and forwards,
64       are implemented in separate packages which are autoloaded into this
65       class.  This means you can simply use these methods as if they are part
66       of this class.  Those package add functionality to all kinds of message
67       objects.
68
69       Extends "DESCRIPTION" in Mail::Reporter.
70

METHODS

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

DETAILS

904   Structure of a Message
905       A MIME-compliant message is build upon two parts: the header and the
906       body.
907
908       The header
909
910       The header is a list of fields, some spanning more than one line
911       (folded) each telling something about the message. Information stored
912       in here are for instance the sender of the message, the receivers of
913       the message, when it was transported, how it was transported, etc.
914       Headers can grow quite large.
915
916       In MailBox, each message object manages exactly one header object (a
917       Mail::Message::Head) and one body object (a Mail::Message::Body).  The
918       header contains a list of header fields, which are represented by
919       Mail::Message::Field objects.
920
921       The body
922
923       The body contains the "payload": the data to be transferred.  The data
924       can be encoded, only accessible with a specific application, and may
925       use some weird character-set, like Vietnamese; the MailBox distribution
926       tries to assist you with handling these e-mails without the need to
927       know all the details.  This additional information ("meta-information")
928       about the body data is stored in the header.  The header contains more
929       information, for instance about the message transport and relations to
930       other messages.
931
932   Message object implementation
933       The general idea about the structure of a message is
934
935        Mail::Message
936         |  |
937         |  `-has-one--Mail::Message::Body
938         |
939         `----has-one--Mail::Message::Head
940                         |
941                         `-has-many--Mail::Message::Field
942
943       However: there are about 7 kinds of body objects, 3 kinds of headers
944       and 3 kinds of fields.  You will usually not see too much of these
945       kinds, because they are merely created for performance reasons and can
946       be used all the same, with the exception of the multipart bodies.
947
948       A multipart body is either a Mail::Message::Body::Multipart (mime type
949       "multipart/*") or a Mail::Message::Body::Nested (mime type
950       "message/rfc822").  These bodies are more complex:
951
952        Mail::Message::Body::Multipart
953         |
954         `-has-many--Mail::Message::Part
955                      |  |
956                      |  `-has-one--Mail::Message::Body
957                      |
958                      `----has-one--Mail::Message::Head
959
960       Before you try to reconstruct multiparts or nested messages yourself,
961       you can better take a look at Mail::Message::Construct::Rebuild.
962
963   Message class implementation
964       The class structure of messages is very close to that of folders.  For
965       instance, a Mail::Box::File::Message relates to a Mail::Box::File
966       folder.
967
968       As extra level of inheritance, it has a Mail::Message, which is a
969       message without location.  And there is a special case of message:
970       Mail::Message::Part is a message encapsulated in a multipart body.
971
972       The message types are:
973
974        Mail::Box::Mbox::Message            Mail::Box::POP3::Message
975        |  Mail::Box::Dbx::Message      Mail::Box::IMAP4::Message  |
976        |  |                                                    |  |
977        Mail::Box::File::Message             Mail::Box::Net::Message
978                |                                      |
979                |       Mail::Box::Maildir::Message    |
980                |       |   Mail::Box::MH::Message     |
981                |       |   |                          |
982                |       Mail::Box::Dir::Message        |
983                |                |                     |
984                `------------.   |   .-----------------'
985                             |   |   |
986                          Mail::Box::Message    Mail::Message::Part
987                                 |                     |
988                                 |       .-------------'
989                                 |       |
990                             Mail::Message
991                                 |
992                                 |
993                           Mail::Reporter (general base class)
994
995       By far most folder features are implemented in Mail::Box, so available
996       to all folder types.  Sometimes, features which appear in only some of
997       the folder types are simulated for folders that miss them, like sub-
998       folder support for MBOX.
999
1000       Two strange other message types are defined: the Mail::Message::Dummy,
1001       which fills holes in Mail::Box::Thread::Node lists, and a
1002       Mail::Box::Message::Destructed, this is an on purpose demolished
1003       message to reduce memory consumption.
1004
1005   Labels
1006       Labels (also named "Flags") are used to indicate some special condition
1007       on the message, primary targeted on organizational issues: which
1008       messages are already read or should be deleted.  There is a very strong
1009       user relation to labels.
1010
1011       The main complication is that each folder type has its own way of
1012       storing labels.  To give an indication: MBOX folders use "Status" and
1013       "X-Status" header fields, MH uses a ".mh-sequences" file, MAILDIR
1014       encodes the flags in the message's filename, and IMAP has flags as part
1015       of the protocol.
1016
1017       Besides, some folder types can store labels with user defined names,
1018       where other lack that feature.  Some folders have case-insensitive
1019       labels, other don't. Read all about the specifics in the manual page of
1020       the message type you actually have.
1021
1022       Predefined labels
1023
1024       To standardize the folder types, MailBox has defined the following
1025       labels, which can be used with the label() and labels() methods on all
1026       kinds of messages:
1027
1028       ·   deleted
1029
1030           This message is flagged to be deleted once the folder closes.  Be
1031           very careful about the concept of 'delete' in a folder context : it
1032           is only a flag, and does not involve immediate action!  This means,
1033           for instance, that the memory which is used by Perl to store the
1034           message is not released immediately (see destruct() if you need
1035           to).
1036
1037           The methods delete(), deleted(), and isDeleted() are only short-
1038           cuts for managing the "delete" label (as of MailBox 2.052).
1039
1040       ·   draft
1041
1042           The user has prepared this message, but is has not been send (yet).
1043           This flag is not automatically added to a message by MailBox, and
1044           has only a meaning in user applications.
1045
1046       ·   flagged
1047
1048           Messages can be flagged for some purpose, for instance as result of
1049           a search for spam in a folder.  The Mail::Box::messages() method
1050           can be used to collect all these flagged messages from the folder.
1051
1052           Probably it is more useful to use an understandable name (like
1053           "spam") for these selections, however these self-defined labels can
1054           not stored in all folder types.
1055
1056       ·   old
1057
1058           The message was already in the folder when it was opened the last
1059           time, so was not recently added to the folder.  This flag will
1060           never automatically be set by MailBox, because it would probably
1061           conflict with the user's idea of what is old.
1062
1063       ·   passed
1064
1065           Not often used or kept, this flag indicates that the message was
1066           bounced or forwarded to someone else.
1067
1068       ·   replied
1069
1070           The user (or application) has sent a message back to the sender of
1071           the message, as response of this one.  This flag is automatically
1072           set if you use reply(), but not with forward() or bounce().
1073
1074       ·   seen
1075
1076           When this flag is set, the receiver of the message has consumed the
1077           message.  A mail user agent (MUA) will set this flag when the user
1078           has opened the message once.
1079
1080       Status and X-Status fields
1081
1082       Mbox folders have no special means of storing information about
1083       messages (except the message separator line), and therefore have to
1084       revert to adding fields to the message header when something special
1085       comes up.  This feature is also enabled for POP3, although whether that
1086       works depends on the POP server.
1087
1088       All applications which can handle mbox folders support the "Status" and
1089       "X-Status" field convensions.  The following encoding is used:
1090
1091        Flag   Field       Label
1092        R      Status   => seen    (Read)
1093        O      Status   => old     (not recent)
1094        A      X-Status => replied (Answered)
1095        F      X-Status => flagged
1096
1097       There is no special flag for "deleted", which most other folders
1098       support: messages flagged to be deleted will never be written to a
1099       folder file when it is closed.
1100

DIAGNOSTICS

1102       Error: Cannot coerce a $class object into a $class object
1103       Error: Cannot include forward source as $include.
1104           Unknown alternative for the forward(include).  Valid choices are
1105           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
1106
1107       Error: Cannot include reply source as $include.
1108           Unknown alternative for the "include" option of reply().  Valid
1109           choices are "NO", "INLINE", and "ATTACH".
1110
1111       Error: Method bounce requires To, Cc, or Bcc
1112           The message bounce() method forwards a received message off to
1113           someone else without modification; you must specified it's new
1114           destination.  If you have the urge not to specify any destination,
1115           you probably are looking for reply(). When you wish to modify the
1116           content, use forward().
1117
1118       Error: Method forwardAttach requires a preamble
1119       Error: Method forwardEncapsulate requires a preamble
1120       Error: No address to create forwarded to.
1121           If a forward message is created, a destination address must be
1122           specified.
1123
1124       Error: No default mailer found to send message.
1125           The message send() mechanism had not enough information to
1126           automatically find a mail transfer agent to sent this message.
1127           Specify a mailer explicitly using the "via" options.
1128
1129       Error: No rebuild rule $name defined.
1130       Error: Only build() Mail::Message's; they are not in a folder yet
1131           You may wish to construct a message to be stored in a some kind of
1132           folder, but you need to do that in two steps.  First, create a
1133           normal Mail::Message, and then add it to the folder.  During this
1134           Mail::Box::addMessage() process, the message will get coerce()-d
1135           into the right message type, adding storage information and the
1136           like.
1137
1138       Error: Package $package does not implement $method.
1139           Fatal error: the specific package (or one of its superclasses) does
1140           not implement this method where it should. This message means that
1141           some other related classes do implement this method however the
1142           class at hand does not.  Probably you should investigate this and
1143           probably inform the author of the package.
1144
1145       Error: coercion starts with some object
1146

SEE ALSO

1148       This module is part of Mail-Message distribution version 3.008, built
1149       on February 11, 2019. Website: http://perl.overmeer.net/CPAN/
1150

LICENSE

1152       Copyrights 2001-2019 by [Mark Overmeer <markov@cpan.org>]. For other
1153       contributors see ChangeLog.
1154
1155       This program is free software; you can redistribute it and/or modify it
1156       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
1157
1158
1159
1160perl v5.30.1                      2020-01-30                  Mail::Message(3)
Impressum