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 forward, specify a body
232 When you specify forward(body), you have created your own body object
234 to be used as content of the forwarded message. This implies that
235 forward(include) is 'NO': no automatic generation of the forwarded
236 body.
237 forward, inline the original
239 The forward(include) is set to 'INLINE' (the default) This is the most
241 complicated situation, but most often used by MUAs: the original
242 message is inserted textually in the new body. You can set-up
243 automatic stripping of signatures, the way of encapsulation, and texts
244 which should be added before and after the encapsulated part.
245 However, the result may not always be what you expect. For instance,
247 some people use very long signatures which will not be automatically
248 stripped because the pass the threshold. So, you probably need some
249 manual intervention after the message is created and before it is sent.
250 When a binary message is encountered, inlining is impossible. In that
252 case, the message is treated as if 'ENCAPSULATE' was requested.
253 forward, attach the original
255 When forward(include) is explicitly set to 'ATTACH' the result will be
257 a multipart which contains two parts. The first part will be your
258 message, and the second the body of the original message.
259 This means that the headers of the forwarded message are used for the
261 new message, and detached from the part which now contains the original
262 body information. Content related headers will (of course) still be
263 part of that part, but lines line "To" and "Subject" will not be stored
264 with that part.
265 As example of the structural transformation:
267 # code: $original->printStructure;
269 multipart/alternative: The source message
270 text/plain: content in raw text
271 text/html: content as html
272 # code: $fwd = $original->forward(include => 'ATTACH');
274 # code: $fwd->printStructure
275 multipart/mixed: The source message
276 text/plain: prelude/postlude/signature
277 multipart/alternative
278 text/plain: content in raw text
279 text/html: content as html
280 forward, encapsulate the original
282 When forward(include) is explicitly set to 'ENCAPSULATE', then the
284 original message is left in-tact as good as possible. The lines of the
285 original message are used in the main message header but also enclosed
286 in the part header.
287 The encapsulation is implemented using a nested message, content type
289 "message/rfc822". As example of the structural transformation:
290 # code: $original->printStructure;
292 multipart/alternative: The source message
293 text/plain: content in raw text
294 text/html: content as html
295 # code: $fwd = $original->forward(include => 'ENCAPSULATE');
297 # code: $fwd->printStructure
298 multipart/mixed: The source message
299 text/plain: prelude/postlude/signature
300 message/rfc822
301 multipart/alternative: The source message
302 text/plain: content in raw text
303 text/html: content as html
304 The message structure is much more complex, but no information is lost.
306 This is probably the reason why many MUAs use this when the forward an
307 original message as attachment.
308 The main difference between bounce() and forward() is the reason for
310 message processing. The bounce has no intention to modify the content
311 of message: the same information is passed-on to someplace else. This
312 may mean some conversions, but for instance, the Message-ID does not
313 need to be changed.
314 The purpose of forward() is to pass on information which is modified:
316 annotated or reduced. The information is not sent back to the author
317 of the original message (which is implemented by reply()), but to
318 someone else.
319 So: some information comes in, is modified, and than forwarded to
321 someone else. Currently, there are four ways to get the original
322 information included, which are explained in the next sections.
323 After the creation of the forward, you may want to rebuild() the
325 message to remove unnecessary complexities. Of course, that is not
326 required.
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-Box distribution version 2.097, built on
341 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
342
344 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
345 ChangeLog.
346 This program is free software; you can redistribute it and/or modify it
348 under the same terms as Perl itself. See
349 http://www.perl.com/perl/misc/Artistic.html
350perl v5.12.3 2011-01-2M6ail::Message::Construct::Forward(3)