1Mail::Message::ConstrucUts:e:rFoCrownatrrdi(b3u)ted PerlMaDiolc:u:mMeenstsaatgieo:n:Construct::Forward(3)
2
3
4

NAME

6       Mail::Message::Construct::Forward - forwarding a Mail::Message
7

SYNOPSIS

9        my Mail::Message $forward = $message->forward(To => 'you');
10        $forward->send;
11

DESCRIPTION

13       Complex functionality on Mail::Message objects is implemented in
14       different files which are autoloaded.  This file implements the
15       functionality related to creating forwarded messages.
16

METHODS

18   Constructing a message
19       $obj->forward(%options)
20           Forward the content of this message.  The body of the message to be
21           forwarded is encapsulated in some accompanying text (if you have no
22           wish for that, than "bounce" is your choice).  A Mail::Message
23           object is returned on success.
24
25           You may forward a whole message, but also message parts.  You may
26           wish to overrule some of the default header settings for the reply
27           immediately, or you may do that later with "set" on the header.
28
29           When a multi-part body is encountered, and the message is included
30           to ATTACH, the parts which look like signatures will be removed.
31           If only one message remains, it will be the added as single
32           attachment, otherwise a nested multipart will be the result.  The
33           value of this option does not matter, as long as it is present.
34           See "Mail::Message::Body::Multipart".
35
36            -Option    --Default
37             Bcc         undef
38             Cc          undef
39             Date        <now>
40             From        <'to' in current>
41             Message-ID  <uniquely generated>
42             Subject     forwardSubject()
43             To          <required>
44             body        undef
45             include     <if body then 'NO' else C<'INLINE'>>
46             preamble    constructed from prelude and postlude
47             signature   undef
48
49           Bcc => ADDRESSES
50             Receivers of blind carbon copies: their names will not be
51             published to other message receivers.
52
53           Cc => ADDRESSES
54             The carbon-copy receivers, by default none.
55
56           Date => DATE
57             The date to be used in the message sent.
58
59           From => ADDRESSES
60             Your identification, by default taken from the "To" field of the
61             source message.
62
63           Message-ID => STRING
64             Supply a STRING as specific message-id for the forwarded message.
65             By default, one is generated for you.  If there are no angles
66             around your id, they will be added.
67
68           Subject => STRING|CODE
69             Force the subject line to the specific STRING, or the result of
70             the subroutine specified by CODE.  The subroutine will be called
71             passing the subject of the original message as only argument.  By
72             default, the forwardSubject() method is used.
73
74           To => ADDRESSES
75             The destination of your message. Obligatory.  The ADDRESSES may
76             be specified as string, a Mail::Address object, or as array of
77             Mail::Address objects.
78
79           body => OBJECT
80             If you specify a fully prepared body OBJECT, it will be used as
81             forwarded message contents.  In this case, only the headers are
82             constructed for you.
83
84           include => 'NO'|'INLINE'|'ATTACH'|'ENCAPSULATE'
85             Must the message where this is a reply to be included in the
86             message?  When "INLINE" is given, you may pass the options of
87             forwardInline() as well.
88
89             In many applications, the forward option "as attachment" results
90             in a structure which is produced when this option is set to
91             "ENCAPSULATE".  Their default behavior is usually "INLINE".
92
93             It is only possible to inline textual messages, therefore binary
94             or multi-part messages will always be enclosed as attachment.
95             Read the details in section "Creating a forward"..
96
97           preamble => STRING|BODY
98             Part which is attached before the forwarded message.  If no
99             preamble is given, then it is constructed from the prelude and
100             postlude.  When these are also not present, you will still get a
101             one liner: the result of forwardPrelude()
102
103           signature => BODY|MESSAGE
104             The signature to be added in case of a multi-part forward.  The
105             mime-type of the signature body should indicate this is a used as
106             such.  However, in INLINE mode, the body will be taken, a line
107             containing '-- ' added before it, and added behind the epilogue.
108
109       $obj->forwardAttach(%options)
110           Forward the message as flat attachment to the specified "preamble".
111           You can specify all options available to forward(), although a
112           "preamble" which is provided as body object is required, and any
113           specified "body" is ignored.
114
115            -Option  --Default
116             preamble  <required>
117
118           preamble => BODY|PART
119       $obj->forwardEncapsulate(%options)
120           Like forwardAttach(), but in this case the original message is
121           first encapsulated as nested message in a
122           Mail::Message::Body::Nested, and then joint into a multipart.
123
124           You can specify all options available to forward(), although a
125           "preamble" which is provided as body object is required, and any
126           specified "body" is ignored.  Signatures are not stripped.
127           Signatures are not stripped.
128
129            -Option  --Default
130             preamble  <required>
131
132           preamble => BODY|PART
133       $obj->forwardInline(%options)
134           This method is equivalent in behavior to forward() with the option
135           "include" set to 'INLINE'.  You can specify most of the fields
136           which are available to forward() except "include" and "body".
137
138            -Option         --Default
139             is_attached      "[The forwarded message is attached]\n"
140             max_signature    10
141             postlude         undef
142             prelude          undef
143             quote            undef
144             strip_signature  qr/^--\s/
145
146           is_attached => STRING
147             A forward on binary messages can not be inlined.  Therefore, they
148             are automatically translated into an attachment, as made by
149             forwardAttach().  The obligatory preamble option to that method
150             may be specified as option to this method, to be used in case of
151             such a forward of a binary, but is otherwise constructed from the
152             prelude, the value of this option, and the postlude.
153
154           max_signature => INTEGER
155             Passed to Mail::Message::Body::stripSignature(max_lines).  Only
156             effective for single-part messages.
157
158           postlude => BODY
159             The line(s) which to be added after the quoted reply lines.
160             Create a body for it first.  This should not include the
161             signature, which has its own option.  The signature will be added
162             after the postlude when the forwarded message is "INLINE"d.
163
164           prelude => BODY
165             The line(s) which will be added before the quoted forwarded
166             lines.  If nothing is specified, the result of the
167             forwardPrelude() method is used.  When "undef" is specified, no
168             prelude will be added.
169
170           quote => CODE|STRING
171             Mangle the lines of an "INLINE"d reply with CODE, or by
172             prepending a STRING to each line.  The routine specified by CODE
173             is called when the line is in $_.
174
175             By default, nothing is added before each line.  This option is
176             processed after the body has been decoded.
177
178           strip_signature => REGEXP|STRING|CODE
179             Remove the signature of the sender.  The value of this parameter
180             is passed to Mail::Message::Body::stripSignature(pattern), unless
181             the source text is not included.  The signature is stripped from
182             the message before quoting.
183
184       $obj->forwardNo(%options)
185           Construct a forward, where the whole body of the message is already
186           constructed.  That complex body is usually produced in
187           forwardInline(), forwardAttach(), or forwardEncapsulate().
188
189           The %options are the same as for forward() except that "body" is
190           required.  Some other options, like "preamble", are ignored.
191
192            -Option--Default
193             body    <required>
194
195           body => BODY
196       $obj->forwardPostlude()
197           Added after the forwarded message.
198
199           example:
200
201            ---- END forwarded message
202
203       $obj->forwardPrelude()
204           Create a few lines to be included before the forwarded message
205           content.  The return is an array of lines.
206
207           example:
208
209            ---- BEGIN forwarded message
210            From: him@somewhere.else.nl (Original Sender)
211            To: me@example.com (Me the receiver)
212            Cc: the.rest@world.net
213            Date: Wed, 9 Feb 2000 15:44:05 -0500
214            <blank line>
215
216       $obj->forwardSubject(STRING)
217           Create a subject for a message which is a forward from this one.
218           This routine tries to count the level of reply in subject field,
219           and transform it into a standard form.  Please contribute
220           improvements.
221
222           example:
223
224            subject                 --> Forw: subject
225            Re: subject             --> Forw: Re: subject
226            Re[X]: subject          --> Forw: Re[X]: subject
227            <blank>                 --> Forwarded
228

DETAILS

230   Creating a forward
231       The main difference between bounce() and forward() is the reason for
232       message processing.  The bounce has no intention to modify the content
233       of message: the same information is passed-on to someplace else.  This
234       may mean some conversions, but for instance, the Message-ID does not
235       need to be changed.
236
237       The purpose of forward() is to pass on information which is modified:
238       annotated or reduced.  The information is not sent back to the author
239       of the original message (which is implemented by reply()), but to
240       someone else.
241
242       So: some information comes in, is modified, and than forwarded to
243       someone else.  Currently, there are four ways to get the original
244       information included, which are explained in the next sections.
245
246       After the creation of the forward, you may want to rebuild() the
247       message to remove unnecessary complexities.  Of course, that is not
248       required.
249
250       forward, specify a body
251
252       When you specify forward(body), you have created your own body object
253       to be used as content of the forwarded message.  This implies that
254       forward(include) is 'NO': no automatic generation of the forwarded
255       body.
256
257       forward, inline the original
258
259       The forward(include) is set to 'INLINE' (the default) This is the most
260       complicated situation, but most often used by MUAs: the original
261       message is inserted textually in the new body.  You can set-up
262       automatic stripping of signatures, the way of encapsulation, and texts
263       which should be added before and after the encapsulated part.
264
265       However, the result may not always be what you expect.  For instance,
266       some people use very long signatures which will not be automatically
267       stripped because the pass the threshold.  So, you probably need some
268       manual intervention after the message is created and before it is sent.
269
270       When a binary message is encountered, inlining is impossible.  In that
271       case, the message is treated as if 'ENCAPSULATE' was requested.
272
273       forward, attach the original
274
275       When forward(include) is explicitly set to 'ATTACH' the result will be
276       a multipart which contains two parts.  The first part will be your
277       message, and the second the body of the original message.
278
279       This means that the headers of the forwarded message are used for the
280       new message, and detached from the part which now contains the original
281       body information.  Content related headers will (of course) still be
282       part of that part, but lines line "To" and "Subject" will not be stored
283       with that part.
284
285       As example of the structural transformation:
286
287        # code: $original->printStructure;
288        multipart/alternative: The source message
289          text/plain: content in raw text
290          text/html: content as html
291
292        # code: $fwd = $original->forward(include => 'ATTACH');
293        # code: $fwd->printStructure
294        multipart/mixed: The source message
295          text/plain: prelude/postlude/signature
296          multipart/alternative
297            text/plain: content in raw text
298            text/html: content as html
299
300       forward, encapsulate the original
301
302       When forward(include) is explicitly set to 'ENCAPSULATE', then the
303       original message is left in-tact as good as possible.  The lines of the
304       original message are used in the main message header but also enclosed
305       in the part header.
306
307       The encapsulation is implemented using a nested message, content type
308       "message/rfc822".  As example of the structural transformation:
309
310        # code: $original->printStructure;
311        multipart/alternative: The source message
312          text/plain: content in raw text
313          text/html: content as html
314
315        # code: $fwd = $original->forward(include => 'ENCAPSULATE');
316        # code: $fwd->printStructure
317        multipart/mixed: The source message
318          text/plain: prelude/postlude/signature
319          message/rfc822
320             multipart/alternative: The source message
321                text/plain: content in raw text
322                text/html: content as html
323
324       The message structure is much more complex, but no information is lost.
325       This is probably the reason why many MUAs use this when the forward an
326       original message as attachment.
327

DIAGNOSTICS

329       Error: Cannot include forward source as $include.
330           Unknown alternative for the forward(include).  Valid choices are
331           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
332
333       Error: Method forwardAttach requires a preamble
334       Error: Method forwardEncapsulate requires a preamble
335       Error: No address to create forwarded to.
336           If a forward message is created, a destination address must be
337           specified.
338

SEE ALSO

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

LICENSE

344       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
345       contributors see ChangeLog.
346
347       This program is free software; you can redistribute it and/or modify it
348       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
349
350
351
352perl v5.36.0                      2023-01-2M0ail::Message::Construct::Forward(3)
Impressum