=encoding utf8

=head1 NAME

Mail::Message::Construct::Bounce - bounce a Mail::Message

=head1 SYNOPSIS

 $message->bounce(To => 'you')->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 bouncing messages off to other destinations.

=head1 METHODS

=head2 Constructing a message

=over 4

=item $obj-E<gt>B<bounce>([RG-OBJECT|OPTIONS])

The program calling this method considers itself as an intermediate step
in the message delivery process; it therefore leaves a resent group
of header fields as trace.

When a message is received, the Mail Transfer Agent (MTA) adds a
C<Received> field to the header.  As OPTIONS, you may specify lines
which are added to the resent group of that received field.  C<Resent-*>
is prepended before the field-names automatically, unless already present.

You may also specify an instantiated L<Mail::Message::Head::ResentGroup|Mail::Message::Head::ResentGroup> (RG)
object.  See L<Mail::Message::Head::ResentGroup::new()|Mail::Message::Head::ResentGroup/"METHODS"> for the available
options.  This is required if you want to add a new resent group: create
a new C<Received> line in the header as well.

If you are planning to change the body of a bounce message, don't!  Bounced
messages have the same message-id as the original message, and therefore
should have the same content (message-ids are universally unique).  If you
still insist, use L<Mail::Message::body()|Mail::Message/"The body">.

example: 

 my $bounce = $folder->message(3)->bounce(To => 'you', Bcc => 'everyone');

 $bounce->send;
 $outbox->addMessage($bounce);

 my $rg     = Mail::Message::Head::ResentGroup->new(To => 'you',
    Received => 'from ... by ...');
 $msg->bounce($rg)->send;

=back

=head1 DIAGNOSTICS

=over 4

=item Error: Method bounce requires To, Cc, or Bcc

The message L<bounce()|Mail::Message::Construct::Bounce/"Constructing a message"> method forwards a received message off to someone
else without modification; you must specified it's new destination.
If you have the urge not to specify any destination, you probably
are looking for L<reply()|Mail::Message::Construct::Reply/"Constructing a message">. When you wish to modify the content, use
L<forward()|Mail::Message::Construct::Forward/"Constructing a message">.

=back

=head1 SEE ALSO

This module is part of Mail-Box distribution version 2.109,
built on August 19, 2013. Website: F<http://perl.overmeer.net/mailbox/>

=head1 LICENSE

Copyrights 2001-2013 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>