---
name: "Mail::SPF::Util"
section: "3pm"
platform: "linux"
package: "perl-mail-spf"
version: "3.20260331-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Mail::SPF::Util"
---

# Mail::SPF::Util(3pm)

Mail::SPF utility class

## NAME

Mail::SPF::Util - Mail::SPF utility class

## VERSION

version 3.20260331

## SYNOPSIS

```
    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);
```

## DESCRIPTION

**Mail::SPF::Util** is Mail::SPF's utility class.

### Class methods

The following class methods are provided:

- **hostname**: returns *string*

  Returns the fully qualified domain name (FQDN) of the local host.

- **ipv4\_address\_to\_ipv6($ipv4\_address)**: returns *NetAddr::IP*; throws *Mail::SPF::EInvalidOptionValue*

  Converts the specified *NetAddr::IP* IPv4 address into an IPv4-mapped IPv6 address.  Throws a *Mail::SPF::EInvalidOptionValue* exception if the specified IP address is not an IPv4 address.

- **ipv6\_address\_to\_ipv4($ipv6\_address)**: returns *NetAddr::IP*; throws *Mail::SPF::EInvalidOptionValue*

  Converts the specified *NetAddr::IP* IPv4-mapped IPv6 address into a proper IPv4 address.  Throws a *Mail::SPF::EInvalidOptionValue* exception if the specified IP address is not an IPv4-mapped IPv6 address.

- **ipv6\_address\_is\_ipv4\_mapped($ipv6\_address)**: returns *boolean*

  Returns **true** if the specified *NetAddr::IP* IPv6 address is an IPv4-mapped address, **false** otherwise.

- **ip\_address\_to\_string($ip\_address)**: returns *string*; throws *Mail::SPF::EInvalidOptionValue*

  Returns the given *NetAddr::IP* IPv4 or IPv6 address compactly formatted as a *string*.  For IPv4 addresses, this is equivalent to calling NetAddr::IP's `"addr"` method.  For IPv6 addresses, this is equivalent to calling NetAddr::IP's `"short"` method.  Throws a *Mail::SPF::EInvalidOptionValue* exception if the specified object is not a *NetAddr::IP* IPv4 or IPv6 address object.

- **ip\_address\_reverse($ip\_address)**: returns *string*; throws *Mail::SPF::EInvalidOptionValue*

  Returns the `"in-addr.arpa."`/`"ip6.arpa."` reverse notation of the given *NetAddr::IP* IPv4 or IPv6 address.  Throws a *Mail::SPF::EInvalidOptionValue* exception if the specified object is not a *NetAddr::IP* IPv4 or IPv6 address object.

- **valid\_domain\_for\_ip\_address($server, $request, $ip\_address, $domain, $find\_best\_match = false, $accept\_any\_domain = false)**: returns *string* or **undef**

  Finds a valid domain name for the given *NetAddr::IP* IP address that matches the given domain or a sub-domain thereof.  A domain name is valid for the given IP address if the IP address reverse-maps to that domain name in DNS, and the domain name in turn forward-maps to the IP address.  Uses the given *Mail::SPF::Server* and *Mail::SPF::Request* objects to perform DNS look-ups. Returns the validated domain name.

  If `$find_best_match` is **true**, the one domain name is selected that best matches the given domain name, preferring 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 is then effectively unused unless a best match is requested).  Defaults to **false**.

- **sanitize\_string($string)**: returns *string* or **undef**

  Replaces all non-printable or non-ascii characters in a string with their hex-escaped representation (e.g., `"\x00"`).

## SEE ALSO

Mail::SPF

For availability, support, and license information, see the README file included with Mail::SPF.

## AUTHORS

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