1Mail::Message::ConstrucUts:e:rFoCrownatrrdi(b3u)ted PerlMaDiolc:u:mMeenstsaatgieo:n:Construct::Forward(3)
2
6 Mail::Message::Construct::Forward - forwarding a Mail::Message
7
9 my Mail::Message $forward = $message->forward(To => 'you');
10 $forward->send;
11
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
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 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 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 -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 Bcc => ADDRESSES
50 Receivers of blind carbon copies: their names will not be
51 published to other message receivers.
52 Cc => ADDRESSES
54 The carbon-copy receivers, by default none.
55 Date => DATE
57 The date to be used in the message sent.
58 From => ADDRESSES
60 Your identification, by default taken from the "To" field of the
61 source message.
62 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 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 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 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 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 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 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 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 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 $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 -Option --Default
116 preamble <required>
117 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 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 -Option --Default
130 preamble <required>
131 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 -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 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 max_signature => INTEGER
155 Passed to Mail::Message::Body::stripSignature(max_lines). Only
156 effective for single-part messages.
157 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 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 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 By default, nothing is added before each line. This option is
176 processed after the body has been decoded.
177 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 $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 The %options are the same as for forward() except that "body" is
190 required. Some other options, like "preamble", are ignored.
191 -Option--Default
193 body <required>
194 body => BODY
196 $obj->forwardPostlude()
197 Added after the forwarded message.
198 example:
200 ---- END forwarded message
202 $obj->forwardPrelude()
204 Create a few lines to be included before the forwarded message
205 content. The return is an array of lines.
206 example:
208 ---- 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 $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 example:
223 subject --> Forw: subject
225 Re: subject --> Forw: Re: subject
226 Re[X]: subject --> Forw: Re[X]: subject
227 <blank> --> Forwarded
228
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 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 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 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 forward, specify a body
251 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 forward, inline the original
258 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 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 When a binary message is encountered, inlining is impossible. In that
271 case, the message is treated as if 'ENCAPSULATE' was requested.
272 forward, attach the original
274 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 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 As example of the structural transformation:
286 # code: $original->printStructure;
288 multipart/alternative: The source message
289 text/plain: content in raw text
290 text/html: content as html
291 # 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 forward, encapsulate the original
301 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 The encapsulation is implemented using a nested message, content type
308 "message/rfc822". As example of the structural transformation:
309 # code: $original->printStructure;
311 multipart/alternative: The source message
312 text/plain: content in raw text
313 text/html: content as html
314 # 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 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
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 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
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
344 Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
345 contributors see ChangeLog.
346 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/
349perl v5.36.0 2023-01-2M0ail::Message::Construct::Forward(3)