1Mail::Message::Replace:U:sMearilCIonntterrinbeutt(e3d)PMearill:D:oMceusmseangtea:t:iRoenplace::MailInternet(3)
2
3
4

NAME

6       Mail::Message::Replace::MailInternet - fake Mail::Internet
7

INHERITANCE

9        Mail::Message::Replace::MailInternet
10          is a Mail::Message
11          is a Mail::Reporter
12

SYNOPSIS

14        !!! BETA !!!
15
16        # change
17        use Mail::Internet;
18        # into
19        use Mail::Message::Replace::MailInternet;
20        # in existing code, and the code should still work, but
21        # with the Mail::Message features.
22

DESCRIPTION

24       This module is a wrapper around a Mail::Message, which simulates a
25       Mail::Internet object.  The name-space of that module is hijacked and
26       many methods are added.
27
28       Most methods will work without any change, but you may need to have a
29       look at your smtpsend() and send() calls.
30
31       Extends "DESCRIPTION" in Mail::Message.
32

OVERLOADED

METHODS

35       Extends "METHODS" in Mail::Message.
36
37   Constructors
38       Extends "Constructors" in Mail::Message.
39
40       $obj->clone(%options)
41           Inherited, see "Constructors" in Mail::Message
42
43       $obj->dup()
44           Duplicate the message.  The result will again be a Mail::Internet
45           compatible object.
46
47       $obj->empty()
48           Remove all data from this object.  Very dangerous!
49
50       Mail::Message::Replace::MailInternet->new( [$arg], [%options] )
51            -Option    --Defined in     --Default
52             Body                         undef
53             FoldLength                   79
54             Header                       undef
55             MailFrom                     'KEEP'
56             Modify                       0
57             body        Mail::Message    undef
58             body_type   Mail::Message    Mail::Message::Body::Lines
59             deleted     Mail::Message    <false>
60             field_type  Mail::Message    undef
61             head        Mail::Message    undef
62             head_type   Mail::Message    Mail::Message::Replace::MailHeader
63             labels      Mail::Message    {}
64             log         Mail::Reporter   'WARNINGS'
65             messageId   Mail::Message    undef
66             modified    Mail::Message    <false>
67             trace       Mail::Reporter   'WARNINGS'
68             trusted     Mail::Message    <false>
69
70           Body => \@lines
71             Array of "\n" terminated lines.  If not specified, the lines will
72             be read from $arg.
73
74           FoldLength => INTEGER
75             Number of characters permitted on any refolded header line.
76             Passed to Mail::Message::Replace::MailHeader::new(FoldLength).
77
78           Header => OBJECT
79             The Mail::Header object, which is passed here, is a fake one as
80             well...  It is translated into a new(head).  If not given, the
81             header will be parsed from the $arg.
82
83           MailFrom => 'IGNORE'|'ERROR'|'COERCE'|'KEEP'
84             What to do with leading ""From "" lines in e-mail data.  Passed
85             to Mail::Message::Replace::MailHeader::new(MailFrom).
86
87           Modify => BOOLEAN
88             Whether to re-fold all the incoming fields.  Passed to
89             Mail::Message::Replace::MailHeader::new(Modify).
90
91           body => OBJECT
92           body_type => CLASS
93           deleted => BOOLEAN
94           field_type => CLASS
95           head => OBJECT
96           head_type => CLASS
97           labels => ARRAY|HASH
98           log => LEVEL
99           messageId => STRING
100           modified => BOOLEAN
101           trace => LEVEL
102           trusted => BOOLEAN
103
104           example: replace traditional Mail::Internet by this wrapper
105
106             # was
107             use Mail::Internet;
108             my $mi = Mail::Internet->new(@options);
109
110             # becomes
111             use Mail::Message::Replace::MailInternet;
112             my $mi = Mail::Internet->new(@options);
113
114   Attributes
115       $obj->MailFrom( [STRING] )
116           Your email address.
117
118   Constructing a message
119       Extends "Constructing a message" in Mail::Message.
120
121       $obj->add_signature( [$filename] )
122           Replaced by sign(), but still usable. $filename is the file which
123           contains the signature, which defaults to "$ENV{HOME}/.signature".
124
125       $obj->bounce( [<$rg_object|%options>] )
126           Inherited, see "Constructing a message" in
127           Mail::Message::Construct::Bounce
128
129       Mail::Message::Replace::MailInternet->build( [$message|$part|$body],
130       $content )
131           Inherited, see "Constructing a message" in
132           Mail::Message::Construct::Build
133
134       Mail::Message::Replace::MailInternet->buildFromBody($body, [$head],
135       $headers)
136           Inherited, see "Constructing a message" in
137           Mail::Message::Construct::Build
138
139       $obj->extract(\@lines|$fh)
140           Read header and body from an ARRAY or $fh
141
142       $obj->forward(%options)
143           Inherited, see "Constructing a message" in
144           Mail::Message::Construct::Forward
145
146       $obj->forwardAttach(%options)
147           Inherited, see "Constructing a message" in
148           Mail::Message::Construct::Forward
149
150       $obj->forwardEncapsulate(%options)
151           Inherited, see "Constructing a message" in
152           Mail::Message::Construct::Forward
153
154       $obj->forwardInline(%options)
155           Inherited, see "Constructing a message" in
156           Mail::Message::Construct::Forward
157
158       $obj->forwardNo(%options)
159           Inherited, see "Constructing a message" in
160           Mail::Message::Construct::Forward
161
162       $obj->forwardPostlude()
163           Inherited, see "Constructing a message" in
164           Mail::Message::Construct::Forward
165
166       $obj->forwardPrelude()
167           Inherited, see "Constructing a message" in
168           Mail::Message::Construct::Forward
169
170       $obj->forwardSubject(STRING)
171           Inherited, see "Constructing a message" in
172           Mail::Message::Construct::Forward
173
174       $obj->read(\@lines|$fh, %options)
175       Mail::Message::Replace::MailInternet->read(\@lines|$fh, %options)
176           Read header and body from the specified ARRAY or $fh.  When used as
177           object method, Mail::Message::read() is called, to be MailBox
178           compliant.  As class method, the Mail::Internet compatible read is
179           called.  %options are only available in the first case.
180
181            -Option             --Defined in                    --Default
182             body_type            Mail::Message::Construct::Read  undef
183             strip_status_fields  Mail::Message::Construct::Read  <true>
184
185           body_type => CLASS
186           strip_status_fields => BOOLEAN
187       $obj->read_body(\@lines|$fh)
188           Read only the message's body from the ARRAY or $fh.
189
190       $obj->read_header(\@lines|$fh)
191           Read only the message's header from the ARRAY or $fh
192
193       $obj->rebuild(%options)
194           Inherited, see "Constructing a message" in
195           Mail::Message::Construct::Rebuild
196
197       $obj->reply(%options)
198           BE WARNED: the main job for creating a reply is done by
199           Mail::Message::reply(), which may produce a result which is
200           compatible, but may be different from Mail::Internet's version.
201
202            -Option         --Defined in                     --Default
203             Bcc              Mail::Message::Construct::Reply  undef
204             Cc               Mail::Message::Construct::Reply  <'cc' in current>
205             Exclude                                           []
206             From             Mail::Message::Construct::Reply  <'to' in current>
207             Inline                                            >
208             Keep                                              []
209             Message-ID       Mail::Message::Construct::Reply  <uniquely generated>
210             ReplyAll                                          <false>
211             Subject          Mail::Message::Construct::Reply  replySubject()
212             To               Mail::Message::Construct::Reply  <sender in current>
213             body             Mail::Message::Construct::Reply  undef
214             group_reply      Mail::Message::Construct::Reply  <true>
215             header_template                                   $ENV{HOME}/.mailhdr
216             include          Mail::Message::Construct::Reply  'INLINE'
217             max_signature    Mail::Message::Construct::Reply  10
218             message_type     Mail::Message::Construct::Reply  Mail::Message
219             postlude         Mail::Message::Construct::Reply  undef
220             prelude          Mail::Message::Construct::Reply  undef
221             quote            Mail::Message::Construct::Reply  '> '
222             signature        Mail::Message::Construct::Reply  undef
223             strip_signature  Mail::Message::Construct::Reply  qr/^--\s/
224
225           Bcc => ADDRESSES
226           Cc => ADDRESSES
227           Exclude => \@names
228             Remove the fields with the specified names from the produced
229             reply message.
230
231           From => ADDRESSES
232           Inline => STRING
233             Quotation STRING, which is translated into reply(quote).  The
234             normal default of "quote" is "> ", in stead of ">".
235
236           Keep => \@names
237             Copy all header fields with the specified NAMES from the source
238             to the reply message.
239
240           Message-ID => STRING
241           ReplyAll => BOOLEAN
242             Reply to the group?  Translated into reply(group_reply), which
243             has as default the exact oposite of this option, being "true".
244
245           Subject => STRING|CODE
246           To => ADDRESSES
247           body => BODY
248           group_reply => BOOLEAN
249           header_template => $filename|"undef"
250             Read the return header from the template file.  When this is
251             explicitly set to "undef", or the file does not exist, then a
252             header will be created.
253
254           include => 'NO'|'INLINE'|'ATTACH'
255           max_signature => INTEGER
256           message_type => CLASS
257           postlude => BODY|LINES
258           prelude => BODY|LINES
259           quote => CODE|STRING
260           signature => BODY|MESSAGE
261           strip_signature => REGEXP|STRING|CODE
262       $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
263           Inherited, see "Constructing a message" in
264           Mail::Message::Construct::Reply
265
266       $obj->replySubject(STRING)
267       Mail::Message::Replace::MailInternet->replySubject(STRING)
268           Inherited, see "Constructing a message" in
269           Mail::Message::Construct::Reply
270
271       $obj->sign(%options)
272           Add a signature (a few extra lines) to the message.
273
274            -Option   --Default
275             File       undef
276             Signature  ''
277
278           File => $filename
279             Specifies a filename where the signature is in.
280
281           Signature => STRING|\@lines
282             The signature in memory.
283
284   The message
285       Extends "The message" in Mail::Message.
286
287       $obj->container()
288           Inherited, see "The message" in Mail::Message
289
290       $obj->isDummy()
291           Inherited, see "The message" in Mail::Message
292
293       $obj->isPart()
294           Inherited, see "The message" in Mail::Message
295
296       $obj->messageId()
297           Inherited, see "The message" in Mail::Message
298
299       $obj->nntppost(%options)
300           Send an NNTP message (newsgroup message), which is equivalent to
301           Mail::Transport::NNTP or Mail::Message::send() with "via 'nntp'".
302
303            -Option--Default
304             Debug   <false>
305             Host    <from Net::Config>
306             Port    119
307
308           Debug => BOOLEAN
309           Host => $hostname
310           Port => INTEGER
311       $obj->partNumber()
312           Inherited, see "The message" in Mail::Message
313
314       $obj->print( [$fh] )
315           Prints the whole message to the specified $fh, which default to
316           STDOUT.  This calls Mail::Message::print().
317
318       $obj->send($type, %options)
319           Send via Mail Transfer Agents (MUA).  These will be handled by
320           various Mail::Transport::Send extensions.  The "test" $type is not
321           supported.
322
323       $obj->size()
324           Inherited, see "The message" in Mail::Message
325
326       $obj->toplevel()
327           Inherited, see "The message" in Mail::Message
328
329       $obj->write( [$fh] )
330           Inherited, see "The message" in Mail::Message
331
332   The header
333       Extends "The header" in Mail::Message.
334
335       $obj->add(\@lines)
336           Add header lines, which simply calls "Mail::Message::Head::add()"
337           on the header for each specified LINE. The last added LINE is
338           returned.
339
340       $obj->bcc()
341           Inherited, see "The header" in Mail::Message
342
343       $obj->cc()
344           Inherited, see "The header" in Mail::Message
345
346       $obj->clean_header()
347           Not to be used, replaced by header().
348
349       $obj->combine( $tag, [$with] )
350           Not implemented, because I see no use for it.
351
352       $obj->date()
353           Inherited, see "The header" in Mail::Message
354
355       $obj->delete( $name, [$index]] )
356           Delete the fields with the specified $name.  The deleted fields are
357           returned.
358
359           BE WARNED: if no $name is specified, the "delete" is interpreted as
360           the deletion of the message in a folder, so
361           Mail::Box::Message::delete() will be called.  This may have no
362           negative effect at all...
363
364           Calls Mail::Message::Replace::MailHeader::delete()
365
366       $obj->destinations()
367           Inherited, see "The header" in Mail::Message
368
369       $obj->fold( [$length] )
370           Fold all the fields to a certain maximum $length.  Implemented by
371           Mail::Message::Replace::MailHeader::fold()
372
373       $obj->fold_length( [[$tag], $length] )
374           Set the maximum line $length.  $tag is ignored.  Implemented by
375           Mail::Message::Replace::MailHeader::fold_length()
376
377       $obj->from()
378           Inherited, see "The header" in Mail::Message
379
380       $obj->get( $name, [$index] )
381           Get all the header fields with the specified $name.  In scalar
382           context, only the first fitting $name is returned.  Even when only
383           one $name is specified, multiple lines may be returned: some fields
384           appear more than once in a header.  Calls
385           Mail::Message::Replace::MailHeader::get()
386
387       $obj->guessTimestamp()
388           Inherited, see "The header" in Mail::Message
389
390       $obj->head( [$head] )
391           Returns the head of the message, or creates an empty one if none is
392           defined.  The $head argument, which sets the header, is not
393           available for Mail::Internet, but is there to be compatible with
394           the "head" method of Mail::Message.
395
396       $obj->header( [\@lines] )
397           Optionally reads a header from the ARRAY of lines, and then returns
398           those fields as array-ref nicely folded.  Implemented by
399           Mail::Message::Replace::MailHeader::header()
400
401       $obj->nrLines()
402           Inherited, see "The header" in Mail::Message
403
404       $obj->print_header($fh)
405           Calls Mail::Message::Head::Complete::print().
406
407       $obj->replace( $tag, $line, [$index] )
408           Adds LINES to the header, but removes fields with the same name if
409           they already exist.  Calls
410           Mail::Message::Replace::MailHeader::replace()
411
412       $obj->sender()
413           Inherited, see "The header" in Mail::Message
414
415       $obj->study($fieldname)
416           Inherited, see "The header" in Mail::Message
417
418       $obj->subject()
419           Inherited, see "The header" in Mail::Message
420
421       $obj->tidy_headers()
422           No effect anymore (always performed).
423
424       $obj->timestamp()
425           Inherited, see "The header" in Mail::Message
426
427       $obj->to()
428           Inherited, see "The header" in Mail::Message
429
430   The body
431       Extends "The body" in Mail::Message.
432
433       $obj->body($lines|@lines)
434           Returns an ARRAY of lines, representing the body.  With arguments,
435           a new body will be created.  In Mail::Internet, the body is not an
436           object but a simple array.
437
438           BE WARNED: this overrules the Mail::Message::body() method, which
439           may cause some confusion.  Use bodyObject() to get access to that
440           body's data.
441
442       $obj->bodyObject( [$body] )
443           Calls Mail::Message::body(), because that "body" method is
444           overruled by the one which has a Mail::Internet compatible
445           interface.
446
447       $obj->contentType()
448           Inherited, see "The body" in Mail::Message
449
450       $obj->decoded(%options)
451           Inherited, see "The body" in Mail::Message
452
453       $obj->encode(%options)
454           Inherited, see "The body" in Mail::Message
455
456       $obj->isMultipart()
457           Inherited, see "The body" in Mail::Message
458
459       $obj->isNested()
460           Inherited, see "The body" in Mail::Message
461
462       $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
463           Inherited, see "The body" in Mail::Message
464
465       $obj->print_body( [$fh] )
466           Prints the body to the specified $fh, which defaults to STDOUT.
467           This calls Mail::Message::Body::print().
468
469       $obj->remove_sig( [$nrlines] )
470           Remove the signature of a message with a maximum of $nrlines lines,
471           which defaults to 10.  The work is done on the decoded body
472           content, by Mail::Message::Body::stripSignature().
473
474       $obj->smtpsend(%options)
475           This method is calling Mail::Message::send() via "smtp", which is
476           implemented in Mail::Transport::SMTP.  The implementation is
477           slightly different, so this method is not 100% compliant.
478
479            -Option  --Default
480             Debug     <false>
481             Hello     <helo_domain from Net::Config>
482             Host      $ENV{SMTPHOSTS} or from Net::Config
483             MailFrom  $ENV{MAILADDRESS} or $ENV{USER}
484             Port      25
485
486           Debug => BOOLEAN
487           Hello => STRING
488           Host => HOSTNAME
489             Only the first detected HOSTNAME is taken, so differs from the
490             original implementation.
491
492           MailFrom => STRING
493             Your e-mail address.  This simulated Mail::Internet object does
494             not try to create an e-mail address from the sendmail
495             configuration file, because that is generally a bad idea in
496             environments with virtual hosts, as we have now-adays.
497
498           Port => INTEGER
499       $obj->tidy_body()
500           Removes blank lines from begin and end of the body.
501
502   Flags
503       Extends "Flags" in Mail::Message.
504
505       $obj->deleted( [BOOLEAN] )
506           Inherited, see "Flags" in Mail::Message
507
508       $obj->isDeleted()
509           Inherited, see "Flags" in Mail::Message
510
511       $obj->isModified()
512           Inherited, see "Flags" in Mail::Message
513
514       $obj->label($label|PAIRS)
515           Inherited, see "Flags" in Mail::Message
516
517       $obj->labels()
518           Inherited, see "Flags" in Mail::Message
519
520       $obj->labelsToStatus()
521           Inherited, see "Flags" in Mail::Message
522
523       $obj->modified( [BOOLEAN] )
524           Inherited, see "Flags" in Mail::Message
525
526       $obj->statusToLabels()
527           Inherited, see "Flags" in Mail::Message
528
529   The whole message as text
530       Extends "The whole message as text" in Mail::Message.
531
532       $obj->as_mbox_string()
533           Returns the whole message as one string, which can be included in
534           an MBOX folder (while not using Mail::Box::Mbox).  Lines in the
535           body which start with "From " are escaped with an >.
536
537       $obj->file()
538           Inherited, see "The whole message as text" in
539           Mail::Message::Construct::Text
540
541       $obj->lines()
542           Inherited, see "The whole message as text" in
543           Mail::Message::Construct::Text
544
545       $obj->printStructure( [$fh|undef],[$indent] )
546           Inherited, see "The whole message as text" in
547           Mail::Message::Construct::Text
548
549       $obj->string()
550           Inherited, see "The whole message as text" in
551           Mail::Message::Construct::Text
552
553   The nasty bits
554       $obj->isa($class)
555       Mail::Message::Replace::MailInternet->isa($class)
556           Of course, the "isa()" class inheritance check should not see our
557           nasty trick.
558
559   Internals
560       Extends "Internals" in Mail::Message.
561
562       $obj->clonedFrom()
563           Inherited, see "Internals" in Mail::Message
564
565       Mail::Message::Replace::MailInternet->coerce($message)
566           Coerce (adapt type) of the specified $message (anything
567           Mail::Message::coerce() accepts) into an Mail::Internet simulating
568           object.
569
570       $obj->isDelayed()
571           Inherited, see "Internals" in Mail::Message
572
573       $obj->readBody( $parser, $head, [$bodytype] )
574           Inherited, see "Internals" in Mail::Message
575
576       $obj->readFromParser( $parser, [$bodytype] )
577           Inherited, see "Internals" in Mail::Message
578
579       $obj->readHead( $parser, [$class] )
580           Inherited, see "Internals" in Mail::Message
581
582       $obj->recursiveRebuildPart($part, %options)
583           Inherited, see "Internals" in Mail::Message::Construct::Rebuild
584
585       $obj->storeBody($body)
586           Inherited, see "Internals" in Mail::Message
587
588       $obj->takeMessageId( [STRING] )
589           Inherited, see "Internals" in Mail::Message
590
591   Error handling
592       Extends "Error handling" in Mail::Message.
593
594       $obj->AUTOLOAD()
595           Inherited, see "METHODS" in Mail::Message::Construct
596
597       $obj->addReport($object)
598           Inherited, see "Error handling" in Mail::Reporter
599
600       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
601       $callback] )
602       Mail::Message::Replace::MailInternet->defaultTrace(
603       [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
604           Inherited, see "Error handling" in Mail::Reporter
605
606       $obj->errors()
607           Inherited, see "Error handling" in Mail::Reporter
608
609       $obj->log( [$level, [$strings]] )
610       Mail::Message::Replace::MailInternet->log( [$level, [$strings]] )
611           Inherited, see "Error handling" in Mail::Reporter
612
613       $obj->logPriority($level)
614       Mail::Message::Replace::MailInternet->logPriority($level)
615           Inherited, see "Error handling" in Mail::Reporter
616
617       $obj->logSettings()
618           Inherited, see "Error handling" in Mail::Reporter
619
620       $obj->notImplemented()
621           Inherited, see "Error handling" in Mail::Reporter
622
623       $obj->report( [$level] )
624           Inherited, see "Error handling" in Mail::Reporter
625
626       $obj->reportAll( [$level] )
627           Inherited, see "Error handling" in Mail::Reporter
628
629       $obj->shortSize( [$value] )
630       Mail::Message::Replace::MailInternet->shortSize( [$value] )
631           Inherited, see "Error handling" in Mail::Message
632
633       $obj->shortString()
634           Inherited, see "Error handling" in Mail::Message
635
636       $obj->trace( [$level] )
637           Inherited, see "Error handling" in Mail::Reporter
638
639       $obj->warnings()
640           Inherited, see "Error handling" in Mail::Reporter
641
642   Cleanup
643       Extends "Cleanup" in Mail::Message.
644
645       $obj->DESTROY()
646           Inherited, see "Cleanup" in Mail::Reporter
647
648       $obj->destruct()
649           Inherited, see "Cleanup" in Mail::Message
650

DETAILS

652       Extends "DETAILS" in Mail::Message.
653

DIAGNOSTICS

655       Error: Cannot include forward source as $include.
656           Unknown alternative for the forward(include).  Valid choices are
657           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
658
659       Error: Mail::Internet does not support this kind of data
660           The ARGS data can only be a file handle or an ARRAY.  Other data
661           types are not supported (see read() if you want to have more).
662
663       Error: Method bounce requires To, Cc, or Bcc
664           The message bounce() method forwards a received message off to
665           someone else without modification; you must specified it's new
666           destination.  If you have the urge not to specify any destination,
667           you probably are looking for reply(). When you wish to modify the
668           content, use forward().
669
670       Error: Method forwardAttach requires a preamble
671       Error: Method forwardEncapsulate requires a preamble
672       Error: No address to create forwarded to.
673           If a forward message is created, a destination address must be
674           specified.
675
676       Error: No rebuild rule $name defined.
677       Error: Only build() Mail::Message's; they are not in a folder yet
678           You may wish to construct a message to be stored in a some kind of
679           folder, but you need to do that in two steps.  First, create a
680           normal Mail::Message, and then add it to the folder.  During this
681           Mail::Box::addMessage() process, the message will get coerce()-d
682           into the right message type, adding storage information and the
683           like.
684
685       Error: Package $package does not implement $method.
686           Fatal error: the specific package (or one of its superclasses) does
687           not implement this method where it should. This message means that
688           some other related classes do implement this method however the
689           class at hand does not.  Probably you should investigate this and
690           probably inform the author of the package.
691

SEE ALSO

693       This module is part of Mail-Message distribution version 3.012, built
694       on February 11, 2022. Website: http://perl.overmeer.net/CPAN/
695

LICENSE

697       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
698       contributors see ChangeLog.
699
700       This program is free software; you can redistribute it and/or modify it
701       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
702
703
704
705perl v5.34.0                      2022-0M3a-i0l1::Message::Replace::MailInternet(3)
Impressum