Child pages
  • UAPI Functions - EmailAuth::validate_current_spfs

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Description

Excerpt
This function retrieves the the Sender Policy Framework (SPF) records for one or more domains.

Multiexcerpt include
SpaceWithExcerptcom.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier@12665
MultiExcerptNameAPIDisabledSendMailRoleNonVersion
PageWithExcerptLIB:_ServerRoleDisabledAPI

Panel
bgColor#F2F2F2
borderStylenone

Examples


Panel
bgColor#FFFFFF
borderStylenone


Expand
titlecPanel or Webmail Session URL


Code Block
languagetext
https://hostname.example.com:2083/cpsess##########/execute/EmailAuth/validate_current_spfs?domain=example.com

Include Page
LIB:_CallUAPIFromBrowserLink
LIB:_CallUAPIFromBrowserLink


Expand
titleLiveAPI PHP Class


Code Block
languagephp
linenumberstrue
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Validate the domain's SPF records.
$poll = $cpanel->uapi(
    'EmailAuth', 'validate_current_spfs',
    array(
        'domain' => 'example.com'
  )
);

Include Page
LIB:_LiveAPIPHPLink
LIB:_LiveAPIPHPLink


Expand
titleLiveAPI Perl Module


Code Block
languageperl
linenumberstrue
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Validate the domain's SPF records.
my $poll = $cpliveapi->uapi(
    'EmailAuth', 'validate_current_spfs',
    {
        'domain' => 'example.com'
  }
);

Include Page
LIB:_LiveAPIPerlLink
LIB:_LiveAPIPerlLink


Expand
titlecPanel Template Toolkit


Code Block
languagexml
linenumberstrue
<!-- Validate the domain's SPF records. -->
[% data = execute('EmailAuth', 'validate_current_spfs', { 'domain' => 'example.com' }) %]
[% FOREACH q = data.validate_current_spfs %]
     <p>
         [% q %]
     </p>
[% END %]

Include Page
LIB:_TTLink
LIB:_TTLink


Expand
titleCommand Line


Code Block
languagebash
uapi --user=username EmailAuth validate_current_spfs domain=example.com

Include Page
LIB:_UAPICLINote
LIB:_UAPICLINote


Expand
titleOutput (JSON)


Code Block
languagebash
linenumberstrue
{
   "apiversion": 3,
   "module": "EmailAuth",
   "func": "validate_current_spfs",
   "result": {
      "data": [
        {
            "domain": "example.com",
            "state": "VALID",
            "expected": "ip6:0:0:0:0:0:ffff:c0a8:101",
			"ip_address": "0:0:0:0:0:ffff:c0a8:101",
			"ip_version": 6,
            "records": [
                {
                    "state": "PASS",
                    "current": "v=spf1 +a +mx ip6:0:0:0:0:0:ffff:c0a8:101 -all"
                }
            ]
        }
    ],
    "errors": null,
    "messages": null,
    "metadata": {
        "transformed": 1
            },
    "status": 1,
    "warnings": null
    }
}


Include Page
LIB:_cPanelAPIShellNote
LIB:_cPanelAPIShellNote


Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

The domain for which to check the SPF records.

Note
titleNote:

To query multiple domains, duplicate the parameter. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.


A valid domain.example.com

Returns

ReturnTypeDescriptionPossible valuesExample
dataarray of hashes

An array that contains information about a domain's SPF records.

Each hash contains the domain, state, expected, and records returns.

                

domain

string

The queried domain.

This function returns this value in the data array.

A valid domain.example.com

state

string

The SPF record's status.

This function returns this value in the data array.

  • VALID — A single SPF TXT record exists in the domain's DNS with the correct ip_address value or redirect mechanism.
  • MISMATCHED — An SPF TXT record exists for the domain that does not match the ip_address value.
  • MULTIPLE — Multiple SPF TXT records exist in the domain's DNS.
  • MISSING — No SPF TXT record exists for the domain's DNS.
VALID

expected

string

The SPF record for the domain in the DNS.

This function returns this value in the data array.

A valid string.
ip6:0:0:0:0:0:ffff:c0a8:101

ip_address

string

The domain's IP address.

This function returns this value in the data array.

A valid string.0:0:0:0:0:ffff:c0a8:101

ip_version

integer

The IP address version.

This function returns this value in the data array.

  • 4
  • 6
6

records

array of hashes

The SPF records of the domain's DNS.

This function returns this value in the data array.

Each hash contains the current, reason and state returns.

current

string

The SPF record's contents.

This function returns this value in the records array.

A valid string.
v=spf1 +a +mx ip6:0:0:0:0:0:ffff:c0a8:101 ~all

reason

string

The reason why the SPF record is not correct, if one exists.

This function returns this value in the records array.

An error message.

Note
titleNote:

If no errors exist, the function does not return this value.





Expand
titleClick to view...

example.com: Sender is not authorized by default to use 'example.com' in 'helo' identity, however domain is not currently prepared for false failures (mechanism '~all' matched)


state

string

The SPF record's status.

Note
titleNote:

These values correspond with RFC7208 section 2.6.

This function returns this value in the records array.

  • PASS — The SPF record confirms that the ip_address value is a valid sender.
  • NEUTRAL — The current SPF record configuration does not determine the ip_address value's validity.
  • FAIL — The SPF record states that the ip_address value is not a valid sender.
  • SOFTFAIL — The SPF record states that the ip_address value is not a valid sender, but does not FAIL state it.
  • TEMPERROR — The SPF record check resulted in a failure. For example, a network failure.
  • PERMERROR — The domain's SPF records are incorrect and require manual correction.
PASS