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>

perl v5.20.2                                       2015-11-28             Courier::Filter::Module::SendCopy(3pm)