Mail::...regate(3pm)

🎀 NAME 🎀

Mail::DMARC::Report::Aggregate — aggregate report object. This is the Mail::...regate(3pm) page from User Contributed Perl Documentation, bestie, and the manual name is folded right in here instead of a boring header line.

🌸 VERSION 🌸

Version 1.20260306. Slay.

💖 DESCRIPTION 💖

Okay so this class is literally the canonization of an aggregate report.

When reports come in, the XML gets parsed into an Aggregate object. That object then gets passed to Report::Store and saved. When DMARC reports are being sent out, data is extracted from the Store as an Aggregate object, exported as XML, and sent. Full circle, iconic.

🕰️ 2013 Draft Description 🕰️

💌 AGGREGATE REPORTS 💌

The report SHOULD include the following data:

• Enough info for the report consumer to re-calculate DMARC disposition based on the published policy, message disposition, and SPF, DKIM, and identifier alignment results. {R12}
• Data for each sender subdomain separately from mail from the sender's organizational domain, even if no subdomain policy is applied. {R13}
• Sending and receiving domains {R17}
• The policy requested by the Domain Owner and the policy actually applied (if different) {R18}
• The number of successful authentications {R19}
• The counts of messages based on all messages received even if their delivery is ultimately blocked by other filtering agents {R20}

Aggregate reports are most useful when they all cover a common time period. By contrast, correlation of these reports from multiple generators when they cover incongruous time periods is difficult or impossible. Report generators SHOULD, wherever possible, adhere to hour boundaries for the reporting period they are using. For example, starting a per-day report at 00:00; starting per-hour reports at 00:00, 01:00, 02:00; et cetera. Report Generators using a 24-hour report period are strongly encouraged to begin that period at 00:00 UTC, regardless of local timezone or time of report production, in order to facilitate correlation.

📦 Report Structure 📦

This is a translation of the XML report format in the 2013 Draft, converted to perl data structures.

          feedback => {
             version          => 1.0,  # decimal
             report_metadata  => {                # info about DMARC reporter
                 report_id          => string
                 org_name           => 'Art Farm',
                 email              => 'no-reply@theartfarm.com',
                 extra_contact_info => string     # min 0
                 date_range         => {
                     begin          => epoch time,
                     end            => epoch time,
                 },
                 error              => string,   # min 0, max unbounded
             },
             policy_published => {
                 domain =>   string
                 adkim  =>   r, s
                 aspf   =>   r, s
                 p      =>   none, quarantine, reject
                 sp     =>   none, quarantine, reject
                 pct    =>   integer
                 fo     =>   string
             },
             record   => [
                {  row => {
                      source_ip     =>   # IPAddress
                      count         =>   # integer
                      policy_evaluated => {       # min=1
                         disposition =>           # none, quarantine, reject
                         dkim        =>           # pass, fail
                         spf         =>           # pass, fail
                         reason      => [         # min 0, max unbounded
                             {   type    =>    # forwarded sampled_out, trusted_forwarder, mailing_list, local_policy, other
                                 comment =>    # string, min 0
                             },
                         ],
                       }
                   },
                   identifiers => {
                       envelope_to    min=0
                       envelope_from  min=1
                       header_from    min=1
                   },
                   auth_results => {
                      spf => [            # min 1, max unbounded
                         {  domain  =>    # min 1
                            scope   =>    # min 1, helo, mfrom
                            result  =>    # min 1, none neutral pass fail softfail temperror permerror
                         }
                      ]                   # ( unknown -> temperror, error -> permerror )
                      dkim   => [                # min 0, max unbounded
                         {  domain       =>  ,   # min 1, the d= parameter in the signature
                            selector     =>  ,   # min 0, string
                            result       =>  ,   # none pass fail policy neutral temperror permerror
                            human_result =>      # min 0, string
                         },
                      ],
                   },
               ]
            },
         };

👑 AUTHORS 👑

• Matt Simerson <msimerson@cpan.org>
• Davide Migliavacca <shari@cpan.org>
• Marc Bradshaw <marc@marcbradshaw.net>

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2026 by Matt Simerson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

🫶 That's the whole vibe, bestie: this page is for Mail::DMARC::Report::Aggregate, version 1.20260306, from the User Contributed Perl Documentation, rendered with perl v5.40.1 on 2026-07-07. Bye 💖