NAME

       Courier::Filter::Module::SendCopy - Pseudo-filter for the Courier::Filter framework that
       sends a copy of certain messages to additional recipients

SYNOPSIS

           use Courier::Filter::Module::SendCopy;

           my $module = Courier::Filter::Module::SendCopy->new(
               # One or more of the following criteria:
               match_sender                => qr/\@office\.example\.net$/,
               match_recipients            => qr/\@customer\.example\.com$/,
               match_authenticated_user    => 'my-smtp-user-name',

               # One or several copy recipients:
               copy_recipients => [
                   'el-cheffe@office.example.net',
                   'archives@customer.example.com',
               ],

               # Send a copy to the sender? (always/never/indifferent)
               copy_to_sender  => TRUE,    # TRUE/FALSE/undef
           )

           my $filter = Courier::Filter->new(
               ...
               modules     => [ $module ],
               ...
           );

DESCRIPTION

       This class is a filter module for use with Courier::Filter.  If a message matches a given
       set of criteria, a blind carbon copy of the message is sent to a configured list of
       additional recipients by adding them to the message's control file.  This module never
       matches.

   Constructor
       The following constructor is provided:

       new(%options): returns Courier::Filter::Module::SendCopy
           Creates a new SendCopy filter module.

           %options is a list of key/value pairs representing any of the following options:

           match_sender
               A pattern matched against the message's envelope sender.  If not specified, any
               sender qualifies.

           match_recipients
               A pattern matched against all of the message's envelope recipients.  Any of the
               envelope recipients may match.  If no pattern is specified, any recipient
               qualifies.

           match_authenticated_user
               A pattern matched against the user name that was used for authentication during
               submission of the message.  If no pattern is specified, any user or none at all
               qualifies.  If a pattern is specified and no authentication took place during
               submission of the message, the message does not qualify.

           copy_recipients
               One or several addresses a copy of every matching message is sent to in addition
               to the original recipients.  A single address can be specified as a simple scalar;
               a list of several addresses must be specified as an array reference.  Any address
               matching exactly one of the original recipient addresses is skipped.

           copy_to_sender
               Specifies whether a copy of the message should be sent to its envelope sender.  If
               false, no message is ever sent back in copy to its sender, even if the sender is
               included in the "copy_recipients" list.  If true, the sender is always sent a copy
               of the message.  If undef (the default), the sender must be included in the
               "copy_recipients" list to receive a copy of the message.

           Patterns may either be simple strings (for exact, case-sensitive matches) or regular
           expression objects created by the "qr//" operator (for partial matches).

           All options of the Courier::Filter::Module constructor are also supported.  Please see
           "new" in Courier::Filter::Module for their descriptions.

   Instance methods
       See "Instance methods" in Courier::Filter::Module for a description of the provided
       instance methods.

SEE ALSO

       Courier::Filter::Module, Courier::Filter::Overview.

       For AVAILABILITY, SUPPORT and LICENSE information, see Courier::Filter::Overview.

AUTHOR

       Michael Buschbeck <michael@buschbeck.net>