NAME

Mail::DKIM2::Address - Envelope paths, domains and the From header field for DKIM2

SYNOPSIS

use Mail::DKIM2::Address qw(domain_of relaxed_domain_match from_authentic);

my ($domain) = domain_of('<bounce@lists.example.com>');       # lists.example.com
relaxed_domain_match('lists.example.com', 'example.com');     # true
from_authentic('example.com', 'Alice <alice@example.com>');   # true

DESCRIPTION

Addresses as DKIM2 reads them: the domain of an RFC 5321 path, A-labels (-09 section 18), the relaxed domain match (section 7.2), and whether a From header field is Authentic for a signing domain (sections 11 and 14.8). Nothing is exported by default; Mail::DKIM2::Common exports these too, as it did before they moved here in 0.31.

See "CONVENTIONS" in Mail::DKIM2 for the conventions every module follows.

FUNCTIONS

extract_domain($address)

The domain of user@domain or <user@domain>, or undef, exactly as written. Deprecated in 0.31 and to be removed: use "domain_of($address)", which lowercases the domain, drops a trailing dot and reports a domain literal.

to_rfc5321_path($address)

Wraps an address in angle brackets if it has none; undef or empty becomes <>. The form mf= and rt= carry.

domain_of($address)

The domain of an address or RFC 5321 path, as ($domain, $is_literal): the text between the last @ and the closing >, lowercased, with one trailing dot removed (<A@Example.COM.> gives example.com). $is_literal is true for a domain literal such as [192.0.2.1]. The empty list when there is no domain, as for <>. New in 0.23.

to_alabel($domain)

The domain with each non-ASCII label lowercased and written as its A-label (xn-- and the RFC 3492 Punycode), as -09 section 18 has mf=, rt= and From domains compared: b\x{fc}cher.example, as UTF-8 octets, gives xn--bcher-kva.example. ASCII labels are unchanged; a label that is not valid UTF-8 is left as it is. No UTS 46 mapping. New in 0.23.

from_domain(@values)

The domain a From header field is Authentic for (-09 section 11), given the values of every From field in one version of the header: the lowercased A-label domain of its one mailbox, or undef when there is no From field, more than one, a field holding other than exactly one mailbox (a list, a group), or a domain literal. Display names (quoted or RFC 2047) and comments are skipped; Name <addr> and a bare addr both work. New in 0.23.

from_mailbox(@values)

from_domain's reading with the reason when there is no domain, as -09 section 14.8 names them (new in 0.29): ('ok', $domain); ('multiple') for more than one mailbox (two From fields, or a list of addresses); ('literal') for a domain literal; ('none') for no From field or a value that is not one mailbox (a group, no @, bad syntax).

from_authentic($d, @values)

True if from_domain(@values) gives a domain and it relaxed-matches the signing domain $d: the "downwards" match only, with no DNS lookup, which is what the signers use (-09 section 12.4 permits a subdomain d= too, when the From domain's Domain Policy Record allows it; the Verifier checks that). New in 0.23.

from_refusal_note($d, @values)

For the log of a signer that refused a From not Authentic for $d: a line naming the From domain (as "from_domain" finds it, or what is wrong with the field) and $d, and saying that a DKIM2 list's posting address must be in the domain the milter signs with. Both milters log it. New in 0.23.

relaxed_domain_match($p1, $p2)

The relaxed domain match of -09 section 7.2: true if $p1 is $p2 or a subdomain of it. Labels come off the left of $p1 only. Both are compared as A-labels (to_alabel), without regard to case and without a trailing dot. A domain literal on either side never matches (new in 0.23).

from_pair_error($d, $policy, @from_values)

-09 section 14.8 for one signing domain and the From field values it must make Authentic (new in 0.29; the Verifier and the Signer share it): undef when Authentic, else [$state, $text], the state fail, permerror or temperror and the text that follows DKIM2-Signature i=<x>. $policy->($domain) returns that domain's Domain Policy Record as "domain_policy" does, or temperror; it is called only when $d is below the From domain.

parent_from_matcher(@domains)

A Mail::DKIM2::Signer ParentFromCallback that is true for a From domain in @domains, each compared as the callback receives it: an A-label (so bücher.example matches xn--bcher-kva.example), lowercased, without one trailing dot. The milters and dkim2sign build theirs with it. New in 0.30.

AUTHOR

Bron Gondwana <brong@fastmailteam.com>

COPYRIGHT AND LICENSE

Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.