
=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


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

=over 4

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">.

I<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 REFERENCES

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

=head1 COPYRIGHTS

Distribution version 2.058.
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.


