Mail::SPF::Util(3)

💖 Mail::SPF::Util 💖

okay so bestie, this is Mail::SPF::Util — it's the little utility class that hangs out inside Mail::SPF and does all the fiddly little jobs so the main modules don't have to. it's giving "backstage crew who make the whole show work" energy, fr fr. 🎀

---

✨ VERSION ✨

this is version 3.20260331 — iconic, current, no notes. 👑

---

🌸 SYNOPSIS 🌸

here's the vibe check on how you actually call it:

use Mail::SPF::Util;

$hostname = Mail::SPF::Util->hostname;

$ipv6_address_v4mapped =
    Mail::SPF::Util->ipv4_address_to_ipv6($ipv4_address);

$ipv4_address =
    Mail::SPF::Util->ipv6_address_to_ipv4($ipv6_address_v4mapped);

$is_v4mapped =
    Mail::SPF::Util->ipv6_address_is_ipv4_mapped($ipv6_address);

$ip_address_string  = Mail::SPF::Util->ip_address_to_string($ip_address);
$reverse_name       = Mail::SPF::Util->ip_address_reverse($ip_address);

$validated_domain = Mail::SPF::Util->valid_domain_for_ip_address(
    $spf_server, $request,
    $ip_address, $domain,
    $find_best_match,       # defaults to false
    $accept_any_domain      # defaults to false
);

$sanitized_string = Mail::SPF::Util->sanitize_string($string);

literally copy-paste and go, you're welcome. 💅

---

🦋 DESCRIPTION 🦋

so Mail::SPF::Util is, and I quote, Mail::SPF's utility class. that's it, that's the whole personality — it's the friend who always has a charger, a hair tie, and a fully qualified domain name. 🫶

---

🎀 Class methods 🎀

these are the class methods it serves up. all of them. every single one. no skipping. ✨

• hostname: returns string

returns the fully qualified domain name (FQDN) of the local host. yes bestie, the whole thing, not just the cute short nickname. 🏠

• ipv4_address_to_ipv6($ipv4_address): returns NetAddr::IP; throws Mail::SPF::EInvalidOptionValue

takes the NetAddr::IP IPv4 address you hand it and converts it into an IPv4-mapped IPv6 address. and if the address you gave it is not an IPv4 address? it throws a Mail::SPF::EInvalidOptionValue exception at you. read the room, give it the right type. 😭

• ipv6_address_to_ipv4($ipv6_address): returns NetAddr::IP; throws Mail::SPF::EInvalidOptionValue

the reverse glow-up: takes a NetAddr::IP IPv4-mapped IPv6 address and converts it back into a proper IPv4 address. if the address you pass isn't an IPv4-mapped IPv6 address, boom — Mail::SPF::EInvalidOptionValue exception. it's giving strict but fair. 💀

• ipv6_address_is_ipv4_mapped($ipv6_address): returns boolean

returns true if the given NetAddr::IP IPv6 address is an IPv4-mapped address, and false otherwise. a simple yes/no, a vibe check in boolean form. ✅❌

• ip_address_to_string($ip_address): returns string; throws Mail::SPF::EInvalidOptionValue

hands back the given NetAddr::IP IPv4 or IPv6 address, compactly formatted as a string. for IPv4 addresses this is literally the same as calling NetAddr::IP's addr method. for IPv6 addresses it's literally the same as calling NetAddr::IP's short method. and if the object you gave it isn't a NetAddr::IP IPv4 or IPv6 address object? yep — Mail::SPF::EInvalidOptionValue exception. no cap. 🔥

• ip_address_reverse($ip_address): returns string; throws Mail::SPF::EInvalidOptionValue

gives you the in-addr.arpa./ip6.arpa. reverse notation of the given NetAddr::IP IPv4 or IPv6 address — you know, that backwards-looking DNS thing. and if the object isn't a NetAddr::IP IPv4 or IPv6 address object, it throws a Mail::SPF::EInvalidOptionValue exception. same energy as the one above, honestly. 🌈

• valid_domain_for_ip_address($server, $request, $ip_address, $domain, $find_best_match = false, $accept_any_domain = false): returns string or undef

okay this one's the main character of the page, pay attention. ✨

it finds a valid domain name for the given NetAddr::IP IP address that matches the given domain or a sub-domain of it. so like, what makes a domain name "valid" for an IP address? two things, and it needs both: the IP address has to reverse-map to that domain name in DNS, and then the domain name has to forward-map back to the IP address. mutual, reciprocal, both-directions slay. 🔁

it uses the given Mail::SPF::Server and Mail::SPF::Request objects to do the DNS look-ups, and it returns the validated domain name. and if nothing works out? it returns undef. sometimes the answer is just no, bestie. 🥲

• if $find_best_match is true, it selects the one domain name that best matches the given domain name, and it prefers direct matches over sub-domain matches. defaults to false.
• if $accept_any_domain is true, any domain names are considered acceptable, even if they differ completely from the given domain name — which means the given domain name is then effectively unused, unless you requested a best match. defaults to false.

• sanitize_string($string): returns string or undef

replaces all the non-printable or non-ascii characters in a string with their hex-escaped representation, like "\x00". it's basically a little skincare routine for your strings — strips out everything that doesn't belong. 🧖‍♀️💜

---

⭐ SEE ALSO ⭐

• Mail::SPF

and for availability, support, and license information, go read the README file that ships with Mail::SPF. it's all in there, iykyk. 📄

---

👑 AUTHORS 👑

Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>

---

and that's the whole page, bestie!! this was Mail::SPF::Util(3) from the User Contributed Perl Documentation, running on perl v5.42.1, dated 2026-04-23. go forth and convert your IP addresses responsibly. mwah. 💅✨🎀🦋🌸