Our documentation is getting an overhaul! We would like your input! Click here to take a look at the beta launch of our new documentation site! Only cPanel & WHM version 82 documentation exists on our beta at this time. 84 will be added to the new site soon! Leave your feedback here: https://go.cpanel.net/docsfeedback
UAPI Functions - EmailAuth::validate_current_ptrs - Developer Documentation - cPanel Documentation
Child pages
  • UAPI Functions - EmailAuth::validate_current_ptrs
Skip to end of metadata
Go to start of metadata

Description

This function validates the pointer records (PTR) for IPv4 and IPv6 addresses that the account's domains send mail from. It retrieves the PTR records for each IP address and determines which of the domain's IP addresses send mail. It then validates the PTR records for each IP address and validates the A or AAAA records pointing to each domain. This function also ensures that at least one of that domain's A or AAAA records points back to the IP address.

Important:

When you disable the MailSend role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/EmailAuth/validate_current_ptrs?domain=example.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 account's PTR records.
$validate_current_ptr = $cpanel->uapi(
    'EmailAuth', 'validate_current_ptrs',
	array(
		'domain' => 'example.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 account's PTR records.
my $validate_current_ptr = $cpliveapi->uapi(
    'EmailAuth', 'validate_current_ptrs',
	{
		'domain' => 'example.com'
	}
);


Note:

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

 Command Line
uapi --user=username EmailAuth validate_current_ptrs domain=example.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_ptrs",
   "result": {
      "data": [
		{
			"arpa_domain": "1.0.0.10.in-addr.arpa",
			"domain": "example.com",
			"helo": "example.com",
			"state": "VALID",
			"ip_address": "10.0.0.1",
			"ip_version": 4,
			"nameservers": [
					"ns1.example.com",
					"ns2.example.com",
					"ns3.example.com"
					],
			"ptr_records": [
				{
					"domain": "example.com",
					"state": "VALID",
					"forward_records": [ "10.0.0.1" ]
				}
			]
		},
		{
			"arpa_domain": "3.0.0.10.in-addr.arpa",
			"domain": "example.com",
			"helo": "example.com",
            "state": "PTR_MISMATCH",
            "ip_address": "10.0.0.3",
            "ip_version": 4,
			"nameservers": [
					"ns1.example.com",
					"ns2.example.com",
					"ns3.example.com"
					],
            "ptr_records": [
                {
                    "domain": "example.com",
                    "state": "FWD_MISMATCH",
                    "forward_records": [ "192.168.12.34" ]
                }
            ]
        },
		{
			"arpa_domain": "4.3.3.7.0.7.3.0.e.2.a.8.0.0.0.0.0.0.0.0.3.a.5.8.8.b.d.0.1.0.0.2.ip6.arpa",
			"domain": "example.com",
			"helo": "example.com",
			"state": "VALID",
			"ip_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
			"ip_version": 6,
			"nameservers": [
					"ns1.example.com",
					"ns2.example.com",
					"ns3.example.com"
					],
			"ptr_records": [
				{
					"domain": "example.com",
					"state": "VALID",
					"forward_records": [ "2001:0db8:85a3:0000:0000:8a2e:0370:7334" ]
				}
			]
		},
		{
			"arpa_domain": "2.0.0.10.in-addr.arpa",
			"domain": "example.com",
			"helo": "example.com",
			"state": "MISSING_PTR",
			"ip_address": "10.0.0.2",
			"ip_version": 4,
			"nameservers": [
					"ns1.example.com",
					"ns2.example.com",
					"ns3.example.com"
					],
			"ptr_records": [ ]
		},
		{
		    "helo" : "thisothermaildomain.com",
			"ptr_records" : [],
		    "ip_address" : "1.1.1.1.1",
		    "state" : "ERROR",
		    "error" : "1.1.1.1.1 is not a valid IP address.",
		    "domain" : "thisotheremaildomain.com"
		},
        {
            "arpa_domain": "4.0.0.10.in-addr.arpa",
			"domain": "example.com",
			"helo": "example.com",
            "state": "PTR_MISMATCH",
            "ip_address": "10.0.0.4",
            "ip_version": 4,
			"nameservers": [
					"ns1.example.com",
					"ns2.example.com",
					"ns3.example.com"
					],
            "ptr_records": [
                {
                    "domain": "example.com",
                    "state": "MISSING_FWD",
                    "forward_records": [ ]
                }
            ]
        }
	],
	"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 validate the PTR records.

Note:

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

A valid domain.example.com

Returns

ReturnTypeDescriptionPossible valuesExample
dataarray of hashesAn array that contains information about the account's PTR records.

Each hash contains the arpa_domain, domain, helo, ip_version, ip_address, state and error returns and the nameservers and ptr_records array of hashes.

Note:

The system only returns the error value when an invalid IP address exists for the domain in the /etc/mailips file.


arpa_domain

string

The IP address used to perform a reverse DNS (rDNS) lookup.

For more information about rDNS, read our How to Configure Reverse DNS for BIND in WHM documentation.

This function returns this value in the data array.

A valid reversed IP address appended with one of the following:

  • in-addr.arpa — An IPv4 address.
  • ip6.arpa — An IPv6 address.

For information about .arpa domains, read Wikipedia's Reverse DNS lookup article.

Note:

The system does not return this value for a domain with an invalid IP address.

1.0.0.10.in-addr.arpa

domain

string

The queried domain.

This function returns this value in the data array.

A valid domain.example.com

helo

string

The hostname that the domain uses to identify itself to remote SMTP servers.

This function returns this value in the data array.

A valid hostname.example.com

ip_version

integer

The IP version number.

This function returns this value in the data array.

  • 4
  • 6

Note:

The system does not return this value for a domain with an invalid IP address.


4

ip_address

string

The IP address.

This function returns this value in the data array.

A valid IP address.

Note:

The system does not return this value for a domain with an invalid IP address.

10.0.0.1

nameservers

array of strings

The authoritative nameservers for the domain's PTR record.

This function returns this value in the data array.

A list of valid nameservers.ns1.example.com

ptr_records

array of hashes

The domain's PTR records.

This function returns this value in the data array.

Each hash contains the domain, state, and forward_records returns.

Note:

The system does not return this hash for a domain with an invalid IP address.


domain

string

The fully qualified domain name (FQDN) that a PTR record points to.

This function returns this value in the ptr_records array.

A valid domain.example.com

state

string

Whether the domain's PTR record points to a domain with an A (IPv4) or a AAAA (IPv6) record.

This function returns this value in the ptr_records array.

  • VALID — The PTR record is valid.
  • MISSING_FWD — The PTR points to a domain without an A or AAAA record.
  • FWD_MISMATCH — The PTR record points to a domain without an A or AAAA record that points back to the IP address.
VALID

forward_records

array of strings

A list of IP addresses that the domain resolves to for A (IPv4) and AAAA (IPv6) records.

This function returns this value in the ptr_records array.

A list of valid IP addresses.10.0.0.1

state

string

Whether the PTR records are valid for the domain.

This function returns this value in the data array.

  • ERROR — The domain's IP address is invalid. The system returns the reason in the error return.
  • IP_IS_PRIVATE — The IP address exists within a range of private IP addresses.

    Note:

    DNS does not define PTR records for private IP addresses.

  • VALID — The PTR record is valid.

    Note:

    The system only returns a VALID response if all of an IP address's PTR records are valid.

  • MISSING_PTR — No PTR records exist for the IP address.
  • PTR_MISMATCH — One or more PTR records point to a domain that does not point back to the correct IP address.
VALID

error

string

The reason why the system did not validate the domain's IP address.

This function returns this value in the data array.

A valid error message.

Note:

The system only returns this value when an invalid IP address exists for the domain in the /etc/mailips file.

1.1.1.1.1 is not a valid IP address.