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 dif‐
14 ferent files which are autoloaded. This file implements the function‐
15 ality related to creating forwarded messages.
16
18 Constructing a message
19 $obj->forward(OPTIONS)
21 Forward the content of this message. The body of the message to be
23 forwarded is encapsulated in some accompanying text (if you have no
24 wish for that, than "bounce" is your choice). A Mail::Message
25 object is returned on success.
26 You may forward a whole message, but also message parts. You may
28 wish to overrule some of the default header settings for the reply
29 immediately, or you may do that later with "set" on the header.
30 When a multi-part body is encountered, and the message is included
32 to ATTACH, the parts which look like signatures will be removed.
33 If only one message remains, it will be the added as single attach‐
34 ment, otherwise a nested multipart will be the result. The value
35 of this option does not matter, as long as it is present. See
36 "Mail::Message::Body::Multipart".
37 Option --Default
39 Bcc undef
40 Cc undef
41 Date <now>
42 From <'to' in current>
43 Message-ID <uniquely generated>
44 Subject forwardSubject()
45 To <required>
46 body undef
47 include <if body then 'NO' else C<'INLINE'>>
48 preamble constructed from prelude and postlude
49 signature undef
50 . Bcc ADDRESSES
52 Receivers of blind carbon copies: their names will not be pub‐
54 lished to other message receivers.
55 . Cc ADDRESSES
57 The carbon-copy receivers, by default none.
59 . Date DATE
61 The date to be used in the message sent.
63 . From ADDRESSES
65 Your identification, by default taken from the "To" field of
67 the source message.
68 . Message-ID STRING
70 Supply a STRING as specific message-id for the forwarded mes‐
72 sage. By default, one is generated for you. If there are no
73 angles around your id, they will be added.
74 . Subject STRING⎪CODE
76 Force the subject line to the specific STRING, or the result of
78 the subroutine specified by CODE. The subroutine will be
79 called passing the subject of the original message as only
80 argument. By default, the forwardSubject() method is used.
81 . To ADDRESSES
83 The destination of your message. Obligatory. The ADDRESSES may
85 be specified as string, a Mail::Address object, or as array of
86 Mail::Address objects.
87 . body OBJECT
89 If you specify a fully prepared body OBJECT, it will be used as
91 forwarded message contents. In this case, only the headers are
92 constructed for you.
93 . include 'NO'⎪'INLINE'⎪'ATTACH'⎪'ENCAPSULATE'
95 Must the message where this is a reply to be included in the
97 message? When "INLINE" is given, you may pass the options of
98 forwardInline() as well.
99 In many applications, the forward option "as attachment"
101 results in a structure which is produced when this option is
102 set to "ENCAPSULATE". Their default behavior is usually
103 "INLINE".
104 It is only possible to inline textual messages, therefore
106 binary or multi-part messages will always be enclosed as
107 attachment. Read the details in section "Creating a forward"..
108 . preamble STRING⎪BODY
110 Part which is attached before the forwarded message. If no
112 preamble is given, then it is constructed from the prelude and
113 postlude. When these are also not present, you will still get
114 a one liner: the result of forwardPrelude()
115 . signature BODY⎪MESSAGE
117 The signature to be added in case of a multi-part forward. The
119 mime-type of the signature body should indicate this is a used
120 as such. However, in INLINE mode, the body will be taken, a
121 line containing '-- ' added before it, and added behind the
122 epilogue.
123 $obj->forwardAttach(OPTIONS)
125 Forward the message as flat attachment to the specified "preamble".
127 You can specify all options available to "forward()", although a
128 "preamble" which is provided as body object is required, and any
129 specified "body" is ignored.
130 Option --Default
132 preamble <required>
133 . preamble BODY⎪PART
135 $obj->forwardEncapsulate(OPTIONS)
137 Like forwardAttach(), but in this case the original message is
139 first encapsulated as nested message in a Mail::Mes‐
140 sage::Body::Nested, and then joint into a multipart.
141 You can specify all options available to "forward()", although a
143 "preamble" which is provided as body object is required, and any
144 specified "body" is ignored. Signatures are not stripped. Signa‐
145 tures are not stripped.
146 Option --Default
148 preamble <required>
149 . preamble BODY⎪PART
151 $obj->forwardInline(OPTIONS)
153 This method is equivalent in behavior to forward() with the option
155 "include" set to 'INLINE'. You can specify most of the fields
156 which are available to forward() except "include" and "body".
157 Option --Default
159 is_attached "[The forwarded message is attached]\n"
160 max_signature 10
161 postlude undef
162 prelude undef
163 quote undef
164 strip_signature qr/^--\s/
165 . is_attached STRING
167 A forward on binary messages can not be inlined. Therefore,
169 they are automatically translated into an attachment, as made
170 by forwardAttach(). The obligatory preamble option to that
171 method may be specified as option to this method, to be used in
172 case of such a forward of a binary, but is otherwise con‐
173 structed from the prelude, the value of this option, and the
174 postlude.
175 . max_signature INTEGER
177 Passed to Mail::Message::Body::stripSignature(max_lines). Only
179 effective for single-part messages.
180 . postlude BODY
182 The line(s) which to be added after the quoted reply lines.
184 Create a body for it first. This should not include the signa‐
185 ture, which has its own option. The signature will be added
186 after the postlude when the forwarded message is "INLINE"d.
187 . prelude BODY
189 The line(s) which will be added before the quoted forwarded
191 lines. If nothing is specified, the result of the forwardPre‐
192 lude() method is used. When "undef" is specified, no prelude
193 will be added.
194 . quote CODE⎪STRING
196 Mangle the lines of an "INLINE"d reply with CODE, or by
198 prepending a STRING to each line. The routine specified by
199 CODE is called when the line is in $_.
200 By default, nothing is added before each line. This option is
202 processed after the body has been decoded.
203 . strip_signature REGEXP⎪STRING⎪CODE
205 Remove the signature of the sender. The value of this parame‐
207 ter is passed to Mail::Message::Body::stripSignature(pattern),
208 unless the source text is not included. The signature is
209 stripped from the message before quoting.
210 $obj->forwardNo(OPTIONS)
212 Construct a forward, where the whole body of the message is already
214 constructed. That complex body is usually produced in for‐
215 wardInline(), forwardAttach(), or forwardEncapsulate().
216 The OPTIONS are the same as for "forward()" except that "body" is
218 required. Some other options, like "preamble", are ignored.
219 Option--Default
221 body <required>
222 . body BODY
224 $obj->forwardPostlude
226 Added after the forwarded message.
228 Example:
230 ---- END forwarded message
232 $obj->forwardPrelude
234 Create a few lines to be included before the forwarded message con‐
236 tent. The return is an array of lines.
237 Example:
239 ---- BEGIN forwarded message
241 From: him@somewhere.else.nl (Original Sender)
242 To: me@example.com (Me the receiver)
243 Cc: the.rest@world.net
244 Date: Wed, 9 Feb 2000 15:44:05 -0500
245 <blank line>
246 $obj->forwardSubject(STRING)
248 Create a subject for a message which is a forward from this one.
250 This routine tries to count the level of reply in subject field,
251 and transform it into a standard form. Please contribute improve‐
252 ments.
253 Example:
255 subject --> Forw: subject
257 Re: subject --> Forw: Re: subject
258 Re[X]: subject --> Forw: Re[X]: subject
259 <blank> --> Forwarded
260
262 Creating a forward
263 The main difference between bounce() and forward() is the reason for
265 message processing. The bounce has no intention to modify the content
266 of message: the same information is passed-on to someplace else. This
267 may mean some conversions, but for instance, the Message-ID does not
268 need to be changed.
269 The purpose of forward() is to pass on information which is modified:
271 annotated or reduced. The information is not sent back to the author
272 of the original message (which is implemented by reply()), but to some‐
273 one else.
274 So: some information comes in, is modified, and than forwarded to some‐
276 one else. Currently, there are four ways to get the original informa‐
277 tion included, which are explained in the next sections.
278 After the creation of the forward, you may want to rebuild() the mes‐
280 sage to remove unnecessary complexities. Of course, that is not
281 required.
282 forward, specify a body
284 When you specify forward(body), you have created your own body object
286 to be used as content of the forwarded message. This implies that for‐
287 ward(include) is 'NO': no automatic generation of the forwarded body.
288 forward, inline the original
290 The forward(include) is set to 'INLINE' (the default) This is the most
292 complicated situation, but most often used by MUAs: the original mes‐
293 sage is inserted textually in the new body. You can set-up automatic
294 stripping of signatures, the way of encapsulation, and texts which
295 should be added before and after the encapsulated part.
296 However, the result may not always be what you expect. For instance,
298 some people use very long signatures which will not be automatically
299 stripped because the pass the threshold. So, you probably need some
300 manual intervention after the message is created and before it is sent.
301 When a binary message is encountered, inlining is impossible. In that
303 case, the message is treated as if 'ENCAPSULATE' was requested.
304 forward, attach the original
306 When forward(include) is explicitly set to 'ATTACH' the result will be
308 a multipart which contains two parts. The first part will be your mes‐
309 sage, and the second the body of the original message.
310 This means that the headers of the forwarded message are used for the
312 new message, and detached from the part which now contains the original
313 body information. Content related headers will (of course) still be
314 part of that part, but lines line "To" and "Subject" will not be stored
315 with that part.
316 As example of the structural transformation:
318 # code: $original->printStructure;
320 multipart/alternative: The source message
321 text/plain: content in raw text
322 text/html: content as html
323 # code: $fwd = $original->forward(include => 'ATTACH');
325 # code: $fwd->printStructure
326 multipart/mixed: The source message
327 text/plain: prelude/postlude/signature
328 multipart/alternative
329 text/plain: content in raw text
330 text/html: content as html
331 forward, encapsulate the original
333 When forward(include) is explicitly set to 'ENCAPSULATE', then the
335 original message is left in-tact as good as possible. The lines of the
336 original message are used in the main message header but also enclosed
337 in the part header.
338 The encapsulation is implemented using a nested message, content type
340 "message/rfc822". As example of the structural transformation:
341 # code: $original->printStructure;
343 multipart/alternative: The source message
344 text/plain: content in raw text
345 text/html: content as html
346 # code: $fwd = $original->forward(include => 'ENCAPSULATE');
348 # code: $fwd->printStructure
349 multipart/mixed: The source message
350 text/plain: prelude/postlude/signature
351 message/rfc822
352 multipart/alternative: The source message
353 text/plain: content in raw text
354 text/html: content as html
355 The message structure is much more complex, but no information is lost.
357 This is probably the reason why many MUAs use this when the forward an
358 original message as attachment.
359
361 Error: Cannot include forward source as $include.
362 Unknown alternative for the forward(include). Valid choices are "NO",
364 "INLINE", "ATTACH", and "ENCAPSULATE".
365 Error: Method forwardAttach requires a preamble
367 Error: Method forwardEncapsulate requires a preamble
369 Error: No address to create forwarded to.
371 If a forward message is created, a destination address must be speci‐
373 fied.
374
376 This module is part of Mail-Box distribution version 2.070, built on
377 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
378
380 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
381 ChangeLog.
382 This program is free software; you can redistribute it and/or modify it
384 under the same terms as Perl itself. See
385 http://www.perl.com/perl/misc/Artistic.html
386perl v5.8.8 2007-03-2M5ail::Message::Construct::Forward(3)