We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - EmailAuth::validate_current_spfs
Skip to end of metadata
Go to start of metadata

Description

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

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/EmailAuth/validate_current_spfs?domain=example.com&domain=example2.com


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$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',
		'domain' => 'example2.com'
  )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
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',
		'domain' => 'example2.com'
  }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username EmailAuth validate_current_spfs domain=example.com domain=example2.com


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"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"
				}]
			},
			{
				"domain": "example2.com",
				"error": "(XID rm8h9f) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “example2.com”’s “TXT” records.",
				"ip_version": 4,
				"ip_address": "198.252.32.45",
				"records": [],
				"state": "ERROR"
			}
		],
		"errors": null,
		"messages": null,
		"metadata": {
			"transformed": 1
		},
		"status": 1,
		"warnings": null
	}
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

The domain for which to check the SPF records.

Note:

To check multiple domains, duplicate or increment the parameter name. For example, to check three domains, you could:

  • Use the domain parameter multiple times.
  • Use the domaindomain-1, and domain-2 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, stateerrorexpected, 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.
  • ERROR — The record's DNS lookup failed. The function returns the reason in the error return.

Note:

We added the ERROR value in cPanel & WHM version 88.

VALID

error

string

A message that details the reason why the DNS lookup failed.

Note:

  • The function only returns this value when the state return is the ERROR value.
  • We added this return in cPanel & WHM version 88.

This function returns this value in the data array.

An error message.(XID rm8h9f) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “example2.com”’s “TXT” records.

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:

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



 Click 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:

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