NAME

       Courier::Filter::Module::SPFout - Outbound SPF filter module for the Courier::Filter framework

SYNOPSIS

           use Courier::Filter::Module::SPFout;

           my $module = Courier::Filter::Module::SPFout->new(
               match_on            => ['fail', 'permerror', 'temperror'],
               default_response    => $default_response_text,
               force_response      => $force_response_text,
               outbound_ip_addresses
                                   => ['129.257.16.1', '2001:6ag:10e1::1'],
               spf_options         => {
                   # any Mail::SPF::Server options
               },

               logger      => $logger,
               inverse     => 0,
               trusting    => 0,
               testing     => 0,
               debugging   => 0
           );

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

DESCRIPTION

       This class is a filter module for use with Courier::Filter.  It matches a message if any of the receiving
       (local) machine's outbound IP addresses are not authorized to send mail from the envelope sender's (MAIL
       FROM) domain according to that domain's DNS SPF (Sender Policy Framework) record.  This is outbound SPF
       checking.

       The point of inbound SPF checking is for message submission agents (MSAs, smarthosts) to protect others
       against forged envelope sender addresses in messages submitted by the MSA's users.

   Constructor
       The following constructor is provided:

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

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

           trusting
               Disabled.  Since outbound SPF checking, as opposed to inbound SPF checking, is applied to trusted
               (authenticated)  messages  only,  setting  this  module to be trusting does not make sense.  This
               property is thus locked to false.  Also  see  the  description  of  Courier::Message's  "trusted"
               property .

           match_on
               A  reference  to  an  array  containing the set of SPF result codes which should cause the filter
               module to match a message.  Possible result codes  are  "pass",  "fail",  "softfail",  "neutral",
               "none",  "permerror",  and  "temperror".  See the SPF specification for details on the meaning of
               those.  If "temperror" is listed,  an  "temperror"  result  will  by  definition  never  cause  a
               permanent rejection, but only a temporary one.  Defaults to ['fail', 'permerror', 'temperror'].

               Note:   With  early SPF specification drafts as well as the obsolete Mail::SPF::Query module, the
               "permerror" and "temperror" result codes were known as "unknown" and "error",  respectively;  the
               old codes are now deprecated but still supported for the time being.

           default_response
               A string that is to be returned as the module's match result in case of a match, that is when the
               "match_on"  option includes the result code of the SPF check (by default when a message fails the
               SPF check).  However, this default response is used only if the (claimed) envelope sender  domain
               does  not provide an explicit response.  See "default_authority_explanation" in Mail::SPF::Server
               for more information.

               SPF macro substitution is performed on the default response, just like on  explanations  provided
               by domain owners.  If undef, Mail::SPF's default explanation will be used.  Defaults to undef.

           force_response
               Instead  of  merely  specifying  a  default  response  for cases where the sender domain does not
               provide an explicit response, you can also specify a response to be used in all  cases,  even  if
               the  sender  domain  does provide one.  This may be useful if you do not want to confuse your own
               users with 3rd-party provided explanations when in fact they are only dealing  with  your  server
               not wanting to relay their messages.  Defaults to undef.

           outbound_ip_addresses
               A  reference  to an array containing the local system's set of outbound IP addresses that will be
               assumed as the sender IP address in outbound SPF checks.  This set should include all  public  IP
               addresses  that  are  used  for  relaying mail.  By default, automatic discovery of one public IP
               address that is "en route" to "the internet" is attempted for  each  of  IPv4  and  IPv6.   Auto-
               discovery does not work from behind NATs.

           spf_options
               A  hash-ref  specifying  options for the Mail::SPF server object used by this filter module.  See
               "new" in Mail::SPF::Server for the supported options.

           All options of the Courier::Filter::Module constructor (except for  the  trusting  option)  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::SPF, Courier::Filter::Module, Courier::Filter::Overview, Mail::SPF.

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

REFERENCES

       SPF website (Sender Policy Framework)
           <http://www.openspf.org>

       SPF specification
           <http://www.openspf.org/Specifications>

AUTHOR

       Julian Mehnle <julian@mehnle.net>

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