Email::ARF::Report - interpret Abuse Reporting Format (ARF) messages
version 0.012
Achtung! This is a prototype. This module will definitely continue to exist, but maybe the interface will change radically once more people have seen it and tried to use it. Don't rely on its interface to keep you employed, just yet.
my $report = Email::ARF::Report->new($text); if ($report->field('source-ip') eq $our_ip) { my $sender = $report->original_email->header('from'); UserManagement->disable_account($sender); }
ARF, the Abuse Feedback Report Format, is used to report email abuse incidents to an email provider. It includes mechanisms for providing machine-readable details about the incident, a human-readable description, and a copy of the offending message.
This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.
Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.
my $report = Email::ARF::Report->new($message);
Given either an Email::MIME object or a string containing the text of an email message, this method returns a new Email::ARF::Report object. If the given message source is not a valid report in ARF format, an exception is raised.
my $mail = Email::ARF::Report->create( original_email => $email, description => $description, fields => \%fields, # or \@fields header_str => \@headers, );
This method creates a new ARF report from scratch.
The original_email parameter may be given as a string, a string reference, or as an object that provides an as_string method.
original_email
as_string
The optional header_str parameter is an arrayref of name/value pairs to be added as extra headers in the ARF report. The values are expected to be character strings, and will be MIME-encoded as needed. To pass pre-encoded headers, use the header parameter. These are handled by Email::MIME's create constructor.
header_str
header
create
Default values are provided for the following fields:
version - 1 user-agent - Email::ARF::Report/$VERSION feedback-type - other
This method returns an Email::MIME object representing the report.
Note! This method returns a new Email::MIME object each time it is called. If you just want to get a string representation of the report, call "as_string". If you call as_email and make changes to the Email::MIME object, the Email::ARF::Report will not be affected.
"as_string"
as_email
This method returns a string representation of the report.
This method returns an Email::Simple object containing the original message to which the report refers. Bear in mind that this message may have been edited by the reporter to remove identifying information.
This method returns the human-readable description of the report, taken from the body of the human-readable (first) subpart of the report.
my $value = $report->field($field_name); my @values = $report->field($field_name);
This method returns the value for the given field from the second, machine-readable part of the report. In scalar context, it returns the first value for the field.
These methods are shorthand for retrieving the fields of the same name, except for arf_version, which returns the Version header. It has been renamed to avoid confusion with the universal VERSION method.
arf_version
VERSION
http://www.mipassoc.org/arf/
RFC 5965
Ricardo Signes <cpan@semiotic.systems>
This software is copyright (c) 2023 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Email::ARF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Email::ARF
CPAN shell
perl -MCPAN -e shell install Email::ARF
For more information on module installation, please visit the detailed CPAN module installation guide.