Child pages
  • WHM API 1 Functions - 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 an 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 (IPv4) or AAAA (IPv6) 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:

In cPanel & WHM version 78 and later, when you disable the MailSend role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/validate_current_ptrs?api.version=1&domain=example.com
 Command Line
whmapi1 validate_current_ptrs domain=example.com


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{  
   "data":{  
      "payload": [
		{
			"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": [ ]
         }
      ]
	}
  ]
},
   "metadata":{
      "version":1,
      "command":"validate_current_spfs",
      "reason":"OK",
      "result":1
	      }
	}


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM 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
payloadarray 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.


domain

string

The queried domain.

This function returns this value in the payload 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 payload array.

A valid hostname.example.com

ptr_records

array of hashes

The domain's PTR records.

This function returns this value in the payload 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

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 payload 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

ip_version

integer

The IP version number.

This function returns this value in the payload 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 payload 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 payload array.

A list of valid nameservers.ns1.example.com

state

string

Whether the PTR records are valid for the domain.

This function returns this value in the payload 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 record exists 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 payload 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.