Mail::...le::SPF(3pm)

💖 Mail::Milter::Module::SPF — the perl manual, but make it cute ✨

okay bestie, gather round 🫶 this is a page from the User Contributed Perl Documentation for Mail::Milter::Module::SPF, a milter module that uses Sender Policy Framework to decide whether to accept or reject mail. no cap.

---

🌸 NAME 🌸

Mail::Milter::Module::SPF — a milter that uses Sender Policy Framework for accept/reject decisions 💅

---

✨ SYNOPSIS ✨

use Mail::Milter::Module::SPF;

my $milter = new Mail::Milter::Module::SPF;

my $milter2 = &SPF; # convenience

yes, &SPF is literally just the convenience shortcut, we love a lazy queen 🎀

---

🚨 WARNING 🚨

bestie. listen to me. this module is known to have MAJOR problems. It should NOT be used in a production environment at this time. fr fr. I'm not being dramatic, that's just what it says. 💀

---

🦋 DESCRIPTION 🦋

So what does this milter actually do? It rejects any mail from a sender — and we mean the sender in the MAIL FROM part of the SMTP transaction, not the From: header, ok?? those are different things and the difference MATTERS — if that sender's domain publishes an SPF record that denies access to the connection host. it's giving "your domain said no, so no" 🙈

The pass/fail result from SPF is configurable as to whether mail gets accepted or rejected immediately. By default? This module will reject a sender whose SPF lookup returns fail, and let the others pass — while setting a Received-SPF: header with the SPF lookup result. See the methods below for all the little knobs you can tune for different situations, she's customizable 💅

This module needs the Mail::SPF::Query module (version 1.996 or later) installed to fetch the SPF record. no dependency, no lookup, no vibes. 👑

And seriously — be sure to read BUGS at the bottom of this documentation for a list of currently unsupported features. don't skip it. I know you want to skip it. don't. 🫶

---

💜 METHODS 💜

🌟 new()

Creates a SPF object. There are no arguments to configure this module from the constructor; see the methods below for changeable options. constructor said "I'm simple, go bother the setters" ✨

🌟 add_header(HEADERNAME)

Tells this module to append a header on messages which are not rejected, indicating the SPF result value and a comment explaining the result. By default this is enabled with the standard header name "Received-SPF". iconic behavior honestly 🎀

Note that this header is not appended if whitelist_pass(1) is in effect and a sender is whitelisted by a SPF pass result. Why? Because whitelisting skips all other mail processing, so this module can't add headers at the end of processing. it literally cannot reach the finish line 😭

If HEADERNAME is undef, the header is disabled and will not be appended to any message.

This method returns a reference to the object itself, allowing this method call to be chained. chain it like jewelry 💅

🌟 ignore_softfail(FLAG)

If FLAG is 0, a SPF record resulting in softfail will be rejected as if the result were fail. no mercy ✋

If FLAG is 1 (the default), a softfail is ignored, treated as if it returned neutral. she's chill like that 🌸

This method returns a reference to the object itself, allowing this method call to be chained.

🌟 ignore_tempfail(FLAG)

If FLAG is 0 (the default), a DNS lookup which fails the underlying DNS query (a SPF error result) will cause the milter to return a temporary failure result (SMFIS_TEMPFAIL). the DNS ghosted us so we ghost back 💀

If FLAG is 1, a temporary DNS failure will be treated as if the lookup resulted in an empty record set (and thus a SPF none result). "no answer? ok bestie, moving on" 🦋

This method returns a reference to the object itself, allowing this method call to be chained.

🌟 local_rules(RULETEXT)

Add one or more SPF rules to try before a "-all" or "?all" record is encountered, in an attempt to validate the mail. This is useful for enumerating secondary MX servers or non-SRS-compliant forwarding systems which send mail to this host. lowkey a very specific use case but we respect it 🙏

The rules must be contained in a single string, separated by spaces.

This method returns a reference to the object itself, allowing this method call to be chained.

🌟 set_message(MESSAGE)

Sets the message used when rejecting messages. This string may contain the substring %M, which will be replaced by the matching e-mail address, and/or %E, which will be replaced by the SPF explanatory URL and text. personalized rejection letters, we love to see it 💖

This method returns a reference to the object itself, allowing this method call to be chained.

🌟 whitelist_pass(FLAG)

If FLAG is 0 (the default), a SPF pass result will be treated like any other non-failure result, allowing the message to pass through without other special handling. standard, no notes ✨

If FLAG is 1, a SPF pass result will cause this module to return SMFIS_ACCEPT, a value that is used by the accept_break(1) behavior of Mail::Milter::Chain, to ignore the results of other modules in the chain. okay main character energy, skipping the whole line 👑

Note that because SPF does not accept or reject until the MAIL FROM: stage, it may be necessary to embed a DeferToRCPT wrapper into the whitelisting chain. For example,

use Mail::Milter::Chain;
use Mail::Milter::Module::SPF;
use Mail::Milter::Wrapper::DeferToRCPT;

my $spf_whitelisted_chain = new Mail::Milter::Chain(
    &SPF->whitelist_pass(1),
    &DeferToRCPT(new Mail::Milter::Chain(
        $milter1, ...
    ))
)->accept_break(1);

This method returns a reference to the object itself, allowing this method call to be chained.

---

💀 BUGS 💀

okay so this is the part where we hold hands and read the fine print together 🫶

Currently this module only handles IPv4 connecting hosts. IPv6 hosts pass through without any SPF handling. IPv6 said "not today" and walked out 🚶‍♀️

This module does not currently support the "result2()" form of the SPF query for special secondary-MX handling. Currently "local_rules()" must be used to set up SPF exceptions for those secondary MX hosts. workaround era 😭

The "best_guess()" and "trusted_forwarder()" special lookups are not yet supported.

---

👑 AUTHOR 👑

Todd Vierling, <tv@duh.org> <tv@pobox.com> — thank you for your service 🫡💖

---

🌈 SEE ALSO 🌈

• Mail::Milter::Object
• Mail::SPF::Query
• the Sender Policy Framework Web site, http://spf.pobox.com/

---

🎀 POD ERRORS 🎀

Hey! The above document had some coding errors, which are explained below. not me snitching on the docs but ok 🙈

Around line 89:

    You can't have =items (as at line 101) unless the first thing after
    the =over is an =item

---

and that's the whole page bestie, you ate it, you understood it, you're a milter girlie now 💅✨

signing off — this was Mail::...le::SPF(3pm) from the User Contributed Perl Documentation, built with perl v5.36.0 and dated 2023-01-22. mwah 🫶💖