---
name: "Courier::Filter::Module::SPF"
section: "3pm"
platform: "linux"
package: "courier-filter-perl"
version: "0.200+ds-6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Courier::Filter::Module::SPF"
---

# Courier::Filter::Module::SPF(3pm)

SPF filter module for the Courier::Filter framework

## NAME

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

## SYNOPSIS

```
    use Courier::Filter::Module::SPF;

    my $module = Courier::Filter::Module::SPF->new(
        scope               => 'mfrom' || 'helo',
        match_on            => ['fail', 'permerror', 'temperror'],
        default_response    => $default_response_text,
        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 class for use with Courier::Filter.  By default, it matches a message if the sending machine's IP address is *not* authorized to send mail from the envelope sender's (MAIL FROM) domain according to that domain's SPF (Sender Policy Framework) DNS record.  This is classic *inbound* SPF checking.

The point of inbound SPF checking is for receivers to protect *themselves* against forged envelope sender addresses in messages sent by others.

### Constructor

The following constructor is provided:

- **new(%options)**: returns *Courier::Filter::Module::SPF*

  Creates a new **SPF** filter module.

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

  - **scope**

    A string denoting the authorization scope, i.e., identity, on which the SPF check is to be performed.  Defaults to `'mfrom'`. See "scope" in Mail::SPF::Request for a detailed explanation.

  - **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, a `"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) MAIL FROM or HELO domain does not provide a result explanation of its own. 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**.

  - **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.  If any of Mail::SPF::BlackMagic's additional options, such as `"default_policy"` (best-guess) or `"tfwl"` (`"trusted-forwarder.org"` accreditation checking), are specified, a black-magic SPF server object will be created instead.

  - **fallback\_guess**

    - **trusted\_forwarders**

    *Deprecated*.  These options should now be specified as `"default_policy"` and `"tfwl"` keys of the "spf\_options" option instead, although these legacy options will continue to work for the time being.  Furthermore, due to the move from the obsolete Mail::SPF::Query module to the Mail::SPF reference implementation, the Mail::SPF::BlackMagic extension module is now required when using these non-standard options.

  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, 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\>