
=head1 NAME

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


=head1 INHERITANCE


=head1 SYNOPSIS

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


=head1 DESCRIPTION

Complex functionality on L<Mail::Message|Mail::Message> objects is implemented in
different files which are autoloaded.  This file implements the
functionality related to creating forwarded message.



=head1 METHODS


=head2 Constructing a message


$obj-E<gt>B<forward>(OPTIONS)

=over 4

Forward the content of this message.  The body of the message to be forwarded
is encapsulated in some accompanying text (if you have no wish for that, than
C<bounce> is your choice).

You may forward a whole message, but also message parts.
You may wish to overrule some of the default header settings for the
reply immediately, or you may do that later with C<set> on the header.

 Option           Defined in       Default                                     
 Bcc                               undef                                       
 Cc                                undef                                       
 Date                              <now>                                       
 From                              <'to' in current>                           
 Message-ID                        <uniquely generated>                        
 Subject                           L<forwardSubject()|"Constructing a message">
 To                                <required>                                  
 body                              undef                                       
 include                           C<'INLINE'>                                 
 max_signature                     C<10>                                       
 message_type                      L<Mail::Message|Mail::Message>              
 postlude                          undef                                       
 prelude                           undef                                       
 quote                             undef                                       
 signature                         undef                                       
 strip_signature                   C<qr/^--\s/>                                

. Bcc ADDRESSES

=over 4

Receivers of blind carbon copies: their names will not be published to
other message receivers.

=back

. Cc ADDRESSES

=over 4

The carbon-copy receivers, by default none.

=back

. Date DATE

=over 4

The date to be used in the message sent.

=back

. From ADDRESSES

=over 4

Your identification, by default taken from the C<To> field of the
source message.

=back

. Message-ID STRING

=over 4

Supply a STRING as specific message-id for the reply.  By default, one is
generated for you.  If there are no angles around your id, they will be
added.

=back

. Subject STRING|CODE

=over 4

Force the subject line to the specific STRING, or the result of the
subroutine specified by CODE.  The subroutine will be called passing
the subject of the original message as only argument.  By default,
the L<forwardSubject()|"Constructing a message"> method is used.

=back

. To ADDRESSES

=over 4

The destination of your message. Obligatory.  The ADDRESSES may be
specified as string, a Mail::Address object, or as array of
Mail::Address objects.

=back

. body OBJECT

=over 4

If you specify a fully prepared body OBJECT, it will be used as forwarded
message contents.  In this case, only the headers are constructed for you.

=back

. include 'INLINE'|'ATTACH'

=over 4

Must the message where this is a reply to be included in the message?
With C<INLINE> a forward body is composed. C<ATTACH> will create a multi-part
body, where the original message is added after the specified body.  It is
only possible to inline textual messages, therefore binary or multi-part
messages will always be enclosed as attachment.

=back

. max_signature INTEGER

=over 4

Passed to L<Mail::Message::Body::stripSignature(max_lines)|"Constructing a body">.  Only
effective for single-part messages.

=back

. message_type CLASS

=over 4

Create a message with the requested type.  By default, it will be a
L<Mail::Message|Mail::Message>.  This is correct, because it will be coerced into
the correct folder message type when it is added to that folder.

=back

. postlude BODY

=over 4

The line(s) which to be added after the quoted reply lines.  Create a
body for it first.  This should not include the signature, which has its
own option.  The signature will be added after the postlude when the
forwarded message is C<INLINE>d.

=back

. prelude BODY

=over 4

The line(s) which will be added before the quoted forwarded lines.
If nothing is specified, the result of the L<forwardPrelude()|"Constructing a message"> method
is used.  When C<undef> is specified, no prelude will be added.

=back

. quote CODE|STRING

=over 4

Mangle the lines of an C<INLINE>d reply with CODE, or by prepending a
STRING to each line.  The routine specified by CODE is called when the
line is in C<$_>.

By default, nothing is added before each line.  This option is processed
after the body has been decoded.

=back

. signature BODY|MESSAGE

=over 4

The signature to be added in case of a multi-part forward.  The mime-type
of the signature body should indicate this is a used as such.  However,
in INLINE mode, the body will be taken, a line containing C<'-- '> added
before it, and added behind the epilogue.

=back

. strip_signature REGEXP|STRING|CODE

=over 4

Remove the signature of the sender.  The value of this parameter is
passed to L<Mail::Message::Body::stripSignature(pattern)|"Constructing a body">, unless the
source text is not included.  The signature is stripped from the message
before quoting.

When a multi-part body is encountered, and the message is included to
ATTACH, the parts which look like signatures will be removed.  If only
one message remains, it will be the added as single attachment, otherwise
a nested multipart will be the result.  The value of this option does not
matter, as long as it is present.  See C<Mail::Message::Body::Multipart>.

=back

=back

$obj-E<gt>B<forwardPostlude>

=over 4

Added after the forwarded message.

I<Example:> 

 ---- END forwarded message

=back

$obj-E<gt>B<forwardPrelude>

=over 4

Create a few lines to be included before the forwarded message
content.  The return is an array of lines.

I<Example:> 

 ---- BEGIN forwarded message
 From: him@somewhere.else.nl (Original Sender)
 To: me@example.com (Me the receiver)
 Cc: the.rest@world.net
 Date: Wed, 9 Feb 2000 15:44:05 -0500
 <blank line>

=back

$obj-E<gt>B<forwardSubject>(STRING)

=over 4

Create a subject for a message which is a forward from this one.  This routine
tries to count the level of reply in subject field, and transform it into
a standard form.  Please contribute improvements.

I<Example:> 

 subject                 --> Forw: subject
 Re: subject             --> Forw: Re: subject
 Re[X]: subject          --> Forw: Re[X]: subject
 <blank>                 --> Forwarded

=back



=head1 DIAGNOSTICS

I<Error:> Cannot include forward source as $include.

Unknown alternative for the L<forward(include)|"Constructing a message">.  Valid choices are
C<NO>, C<INLINE>, and C<ATTACH>.

I<Error:> No address to create forwarded to.

If a forward message is created, a destination address must be specified.






=head1 REFERENCES

See the Mail::Box website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Module version 2.042.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


