Mail::SPF::Result - SPF result class
For the general usage of Mail::SPF::Result objects in code that calls Mail::SPF, see Mail::SPF. For the detailed interface of Mail::SPF::Result and its derivatives, see below.
package Mail::SPF::Foo; use Error ':try'; use Mail::SPF::Result; sub foo { if (...) { throw Mail::SPF::Result::Pass($server, $request); } else { throw Mail::SPF::Result::PermError($server, $request, 'Invalid foo'); } }
package Mail::SPF::Bar; use Error ':try'; use Mail::SPF::Foo; try { Mail::SPF::Foo->foo(); } catch Mail::SPF::Result with { my ($result) = @_; ... };
my $result_code = $result->code; my $request = $result->request; my $local_exp = $result->local_explanation; my $authority_exp = $result->authority_explanation if $result->can('authority_explanation'); my $spf_header = $result->received_spf_header;
An object of class Mail::SPF::Result represents the result of an SPF request.
There is usually no need to construct an SPF result object directly using the new constructor. Instead, use the throw class method to signal to the calling code that a definite SPF result has been determined. In other words, use Mail::SPF::Result and its derivatives just like exceptions. See Error or "eval" in perlfunc for how to handle exceptions in Perl.
new
throw
The following constructor is provided:
Creates a new SPF result object and associates the given Mail::SPF::Server and Mail::SPF::Request objects with it. An optional result text may be specified.
The following class methods are provided:
Throws a new SPF result object, associating the given Mail::SPF::Server and Mail::SPF::Request objects with it. An optional result text may be specified.
Returns the trailing part of the name of the Mail::SPF::Result::* class on which it is invoked. For example, returns NeutralByDefault if invoked on Mail::SPF::Result::NeutralByDefault. This method may also be used as an instance method.
NeutralByDefault
Returns the result code ("pass", "fail", "softfail", "neutral", "none", "error", "permerror", "permerror") of the Mail::SPF::Result::* class on which it is invoked. This method may also be used as an instance method.
"pass"
"fail"
"softfail"
"neutral"
"none"
"error"
"permerror"
Maps the given result code to the corresponding Mail::SPF::Result::* class. If an unknown result code was specified, returns undef.
If the class (or object) on which this method is invoked represents the given result code (or a derivative code), returns true. Returns false otherwise. This method may also be used as an instance method.
For example, Mail::SPF::Result::Pass->is_code('pass') returns true.
Mail::SPF::Result::Pass->is_code('pass')
The following instance methods are provided:
Re-throws an existing SPF result object. If Mail::SPF::Server and Mail::SPF::Request objects are specified, associates them with the result object, replacing the prior server and request objects. If a result text is specified as well, overrides the prior result text.
Returns the result code of the result object.
Returns the Mail::SPF server object that produced the result at hand.
Returns the SPF request that led to the result at hand.
Returns the text message of the result object.
Returns the result's name and text message formatted as a string. You can simply use a Mail::SPF::Result object as a string for the same effect, see "OVERLOADING".
Returns a locally generated explanation for the result.
The local explanation is prefixed with the authority domain whose sender policy is responsible for the result. If the responsible sender policy referred to another domain's policy (using the include mechanism or the redirect modifier), that other domain which is directly responsible for the result is also included in the local explanation's head. For example:
include
redirect
example.com: <local-explanation>
The authority domain example.com's sender policy is directly responsible for the result.
example.com
example.com ... other.example.org: <local-explanation>
The authority domain example.com (directly or indirectly) referred to the domain other.example.org, whose sender policy then led to the result.
other.example.org
Returns a string containing an appropriate Received-SPF header field for the result object. The header field is not line-wrapped and contains no trailing newline character.
Received-SPF
If a Mail::SPF::Result object is used as a string, the "stringify" method is used to convert the object into a string.
The following result classes are provided:
The following additional instance method is provided:
Returns the authority domain's explanation for the result. Be aware that the authority domain may be a malicious party and thus the authority explanation should not be trusted blindly. See RFC 4408, 10.5, for a detailed discussion of this issue.
This is a special-case of the neutral result that is thrown as a default when "falling off" the end of the record during evaluation. See RFC 4408, 4.7.
neutral
The following sub-classes of Mail::SPF::Result::Error are provided:
Mail::SPF, Mail::SPF::Server, Error, "eval" in perlfunc
http://www.ietf.org/rfc/rfc4408.txt
For availability, support, and license information, see the README file included with Mail::SPF.
Julian Mehnle <julian@mehnle.net>
To install Mail::SPF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::SPF
CPAN shell
perl -MCPAN -e shell install Mail::SPF
For more information on module installation, please visit the detailed CPAN module installation guide.