blib/lib/Mail/DMARC/Result.pm untested

filter: Statementstmt 0.0% 0 / 57 Branchbran 0.0% 0 / 32 Conditioncond 0.0% 0 / 8 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 0.0% 0 / 16 Podpod 0.0% 0 / 10 totaltotal 0.0% 0 / 127 CC 17 SCAR 22.0
CC
17
Cov
0%
published
12.0
disposition
12.0
dkim
12.0
CRAP 9.1
1 package Mail::DMARC::Result;
2 our $VERSION = '2.20260827';
3 use strict;
4 use warnings;
5 use feature 'signatures';
6 no warnings 'experimental::args_array_with_signatures'; ## no critic (ProhibitNoWarnings)
7  
8 use Carp;
9 require Mail::DMARC::Result::Reason;
10  
11 sub new($class) {
12 return bless {
13 dkim => '',
14 spf => '',
15 reason => [],
16 },
17 $class;
18 }
19  
20 sub published( $self, $policy = undef ) {
21 if ( !$policy ) {
22 if ( !defined $self->{published} ) {
23 croak
24 "no policy discovered. Did you validate(), or at least fetch_dmarc_record() first? Or inspected results to detect a 'No Results Found' type error?";
25 }
26 return $self->{published};
27 }
28  
29 $policy->{domain}
30 or croak
31 "tag the policy object with a domain indicating where the DMARC record was found!";
32 return $self->{published} = $policy;
33 }
34  
35 sub disposition( $self, $val = undef ) {
36 return $self->{disposition} if @_ == 1;
37 croak 'invalid disposition: ' . ( $val // '(undef)' )
38 if !defined $val || 0 == grep {/^$val$/ix} qw/ reject quarantine none /;
39 return $self->{disposition} = $val;
40 }
41  
42 sub dkim( $self, $val = undef ) {
43 return $self->{dkim} if @_ == 1;
44 croak "invalid dkim" if 0 == grep {/^$val$/ix} qw/ pass fail /;
45 return $self->{dkim} = $val;
46 }
47  
48 sub dkim_align( $self, $val = undef ) {
49 return $self->{dkim_align} if @_ == 1;
50 croak "invalid dkim_align"
51 if 0 == grep {/^$val$/ix} qw/ relaxed strict /;
52 return $self->{dkim_align} = $val;
53 }
54  
55 sub dkim_meta( $self, $val = undef ) {
56 return $self->{dkim_meta} if @_ == 1;
57 return $self->{dkim_meta} = $val;
58 }
59  
60 sub spf( $self, $val = undef ) {
61 return $self->{spf} if @_ == 1;
62 croak "invalid spf" if 0 == grep {/^$val$/ix} qw/ pass fail /;
63 return $self->{spf} = $val;
64 }
65  
66 sub spf_align( $self, $val = undef ) {
67 return $self->{spf_align} if @_ == 1;
68 croak "invalid spf_align" if 0 == grep {/^$val$/ix} qw/ relaxed strict /;
69 return $self->{spf_align} = $val;
70 }
71  
72 sub result( $self, $val = undef ) {
73 return $self->{result} if @_ == 1;
74 croak "invalid result"
75 if !defined $val || 0 == grep {/^$val$/ix} qw/ pass fail none /;
76 return $self->{result} = $val;
77 }
78  
79 sub reason( $self, @args ) {
80 return $self->{reason} if !@args;
81 push @{ $self->{reason} }, Mail::DMARC::Result::Reason->new(@args);
82 return $self->{reason};
83 }
84  
85 1;
86  
87 __END__
88  
89 =pod
90  
91 =head1 NAME
92  
93 Mail::DMARC::Result - an aggregate report result object
94  
95 =head1 VERSION
96  
97 version 2.20260827
98  
99 =head1 OVERVIEW
100  
101 A L<Result|Mail::DMARC::Result> object is the product of instantiating a L<DMARC::PurePerl|Mail::DMARC::PurePerl> object, populating the variables, and running $dmarc->validate. The results object looks like this:
102  
103 result => 'pass', # pass, fail
104 disposition => 'none', # reject, quarantine, none
105 reason => [ # there can be many reasons...
106 {
107 type => '', # forwarded, sampled_out, trusted_forwarder,
108 comment => '', # mailing_list, local_policy, other
109 },
110 ],
111 dkim => 'pass', # pass, fail
112 dkim_align => 'strict', # strict, relaxed
113 spf => 'pass', # pass, fail
114 spf_align => 'strict', # strict, relaxed
115 published => L<Mail::DMARC::Policy>,
116  
117 Reasons are optional and may not be present.
118  
119 The dkim_align and spf_align fields will only be present if the corresponding test value equals pass. They are additional info not specified by the DMARC spec.
120  
121 =head1 METHODS
122  
123 =head2 published
124  
125 Published is a L<Mail::DMARC::Policy> tagged with a domain. The domain attribute is the DNS domain name where the DMARC record was found. This may not be the same as the header_from domain (ex: bounces.amazon.com -vs- amazon.com).
126  
127 =head2 result
128  
129 Whether the message passed the DMARC test. Possible values are: pass, fail.
130  
131 In order to pass, at least one authentication alignment must pass. The 2013 draft defines two authentication methods: DKIM and SPF. The list is expected to grow.
132  
133 =head2 disposition
134  
135 When the DMARC result is not I<pass>, disposition is the results of applying DMARC policy to a message. Generally this is the same as the header_from domains published DMARC L<policy|Mail::DMARC::Policy>. When it is not, the reason SHOULD be specified.
136  
137 =head2 dkim
138  
139 Whether the message passed or failed DKIM alignment. In order to pass the DMARC DKIM alignment test, a DKIM signature that matches the RFC5322.From domain must be present. An unsigned messsage, a message with an invalid signature, or signatures that don't match the RFC5322.From field are all considered failures.
140  
141 =head2 dkim_align
142  
143 If the message passed the DKIM alignment test, this indicates whether the alignment was strict or relaxed.
144  
145 =head2 spf
146  
147 Whether the message passed or failed SPF alignment. To pass SPF alignment, the RFC5321.MailFrom domain must match the RFC5322.From field.
148  
149 =head2 spf_align
150  
151 If the message passed the SPF alignment test, this indicates whether the alignment was strict or relaxed.
152  
153 =head2 reason
154  
155 If the applied policy differs from the sites published policy, the result policy should contain a reason and optionally a comment.
156  
157 A DMARC result reason has two attributes, type, and comment.
158  
159 reason => {
160 type => '',
161 comment => '',
162 },
163  
164 =head3 type
165  
166 The following reason types are defined and valid:
167  
168 forwarded
169 sampled_out
170 trusted_forwarder
171 mailing_list
172 local_policy
173 other
174  
175 =head3 comment
176  
177 Comment is a free form text field.
178  
179 =head1 AUTHORS
180  
181 =over 4
182  
183 =item *
184  
185 Matt Simerson <msimerson@cpan.org>
186  
187 =item *
188  
189 Davide Migliavacca <shari@cpan.org>
190  
191 =item *
192  
193 Marc Bradshaw <marc@marcbradshaw.net>
194  
195 =back
196  
197 =head1 COPYRIGHT AND LICENSE
198  
199 This software is copyright (c) 2026 by Matt Simerson.
200  
201 This is free software; you can redistribute it and/or modify it under
202 the same terms as the Perl 5 programming language system itself.
203  
204 =cut