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_dkims
Skip to end of metadata
Go to start of metadata

Description

This function retrieves and checks the Domain Keys Identified Mail (DKIM) records for one or more domains.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/EmailAuth/validate_current_dkims?domain=example.com&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.
 
// Retrieve a domain's DKIM records.
$poll = $cpanel->uapi(
    'EmailAuth', 'validate_current_dkims',
    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.
 
# Retrieve a domain's DKIM records.
my $poll = $cpliveapi->uapi(
    'EmailAuth', 'validate_current_dkims',
    {
        '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_dkims 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_dkims",
	"result": {
		"data": [{
			"domain": "default._domainkey.example.com",
			"state": "VALID",
			"validity_cache_update": "valid",
			"expected": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB\\",
			"records": [{
					"state": "VALID",
					"current": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB\\"
			},
			{
			"validity_cache_update": "none",
			"records": [],
			"error": "(XID 4krw35) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “default._domainkey.example2.com”’s “TXT” records.",
			"domain": "default._domainkey.example2.com",
			"expected": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4mA8NH3BkYvOmB0+ql29U78JesahG8304unKhW+MAm0ZE+i6EMO6iXhUj7FRPvI/6jFRd7qAHCPKFLo5+/PTy8C8eK312tuSnF3N0eucYFbgZ8F8iSRdgrcgEjvJ1vM1uvcUF222yd/e3jxT2Ge4/fmZcTYNjfH3uAuriv61L6pdIwHUWPhcjQvgOQoKQgXgooCUbUkWFDkMAH+EF/0g1dnXf289LjlvQsKhY7Y135Zpvm21kjUcj5mrLDlHJALzCVb8K/r/LCxjV5GFUyJiiNLAxkI9V1vZ4pMQvKIsN7wzu6gXK87w6mEWvKvipMAP8A2choDrk6H/fcQtfNodgwIDAQAB;",
			"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 DKIM 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 that exists on the cPanel account.example.com

Returns

ReturnTypeDescriptionPossible valuesExample
dataarray of hashes

An array that contains information about the domain's DKIM records.

Each hash contains the domain, stateerrorexpected, and validity_cache_update returns, and the records array of hashes.

                

domain

string

The domain that the function used to check the DKIM record.

This function returns this value in the data array.

The value of the domain parameter with a default._domainkey prefix.

default._domainkey.example.com

state

string

The domain's DKIM record status.

This function returns this value in the data array.

  • VALID — The DKIM record is valid.
  • MALFORMED — A single DKIM record exists, but the record does not match the expected DKIM specifications.
  • MISMATCH — A DKIM record exists, but it does not match the expected public key.
  • MISSING — No DKIM record exists for the domain.
  • MULTIPLE — Multiple DKIM records exist.
  • NOPUB — No key exists on the local server for the domain.
  • 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 4krw35) DNS returned “SERVFAIL” (code 2) in response to the system’s query for “default._domainkey.example2.com”’s “TXT” records.

expected

string

The DKIM record's contents.

This function returns this value in the data array.

A valid string.
 Click to view...

v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB

validity_cache_update

string

The result of the DKIM record's validity cache update operation.

This function returns this value in the data array.

  • set — The domain is invalid but passed its validity check. The validity check now passes the domain as valid.
  • unset — The domain is invalid and did not pass its validity check. The validity check does not pass the domain as valid.
  • valid — The domain is valid and passed its validity check. There are no changes required.
  • invalid — The domain is invalid and failed its validity check. There are no changes required.
  • none — The domain is invalid, but the system will not take further action.
  • error — The domain's validity check operation failed.
valid

records

array of hashes

The domain's DNS DKIM TXT records.

Important:

This function may fail to preserve whitespace in DKIM records.

This function returns this value in the data array.

Each hash contains the current, reason, and state returns.

current

string

The domain's DKIM TXT record data contents.

Important:

This function may fail to preserve whitespace in DKIM records.

This function returns this value in the records array.

The full contents of the domain's DKIM TXT record.
 Click to view...

v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDw5nw4NP1RsWXlfmiMzByDfOT16QCZO\/xJtrPZKskZF8\/sU0zWGTqKUOErlyJfoJzMDUv3\/zzjGswc2nEmYqxxoQZaBkN4QaS6MvJQxysAr+sK8C248\/r9zMperQdhJedUVejtpFQHJwgqpHy1tQMxY37L7sQjdxmQ5WnQ1acXiwIDAQAB

reason

string

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

Note:

This function only returns this value when this hash's state return is the PERMFAIL value.

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: The DKIM version must be "DKIM1".

state

string

The DKIM TXT record's status.

This function returns this value in the records array.

  • VALID — The DKIM TXT record matches the local server's public key.
  • MISMATCH — The DKIM TXT record does not match the local server's public key.
  • PERMFAIL — Multiple DKIM TXT records for the domain exist or a misconfigured DKIM TXT record exists.

VALID