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>