cPanel/EmailAuth
cPanel module

EmailAuth

12 functions, invoked through the cpanel_uapi tool.

scope cpanel:uapi
Call any function with cpanel_uapi(service_id, module="EmailAuth", function, params). Live availability depends on the cPanel features JetHost has enabled on your account — call list_cpanel_operations to see what is active.

apply_dmarc GET#

Apply DMARC records to domains.

This function applies a DMARC record to the specified domain(s)

policystringRequired
The DMARC record to apply to the requested domains. Note: Visit the following link for more information about the DMARC record specification: https://dmarc.org/resources/specification/
domainstringOptional
The domain for which to apply the DMARC record. Note: To enable multiple domain DMARC records, duplicate or increment the parameter. For example, to enable DMARC records for three domains, perform either of the following actions: Use the domain parameter three times. Use the domain, domain-1, and domain-2 parameters. If you do not include this argument, the system applies the DMARC record to all the user's domains. You cannot use this function to edit temporary domains' DMARC records.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain for which the DMARC record was applied.
msgstring
The domain's DMARC record status message.
statusinteger
Whether the system applied a DMARC record to the domain. 1 - Applied. 0 - The system did not apply a DMARC record.
One of: 0 1

disable_dkim GET#

Remove domains' DKIM records

This function removes the DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

domainstringRequired
The domain for which to remove DKIM records on the DNS server. Note: To remove multiple domain DKIM records, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain for which the system removed the DKIM record.
msgstring
Information about the removed DKIM record.
statusinteger
Whether the system removed the domain's DKIM record on the DNS server. 1 - The system removed the domain's DKIM record. 0 - The system did not remove the domain's DKIM record.
One of: 0 1

enable_dkim GET#

Enable domains' DKIM records

This function enables DomainKeys Identified Mail (DKIM) records on the DNS server for one or more domains.

Note:

If a DKIM record does not exist on the server, this function will install a new DKIM record.

domainstringRequired
The domain for which to enable DKIM records on the DNS server. Note: To enable multiple domain DKIM records, duplicate or increment the parameter. For example, to perform this for three domains, you could: Use the domain parameter multiple times. Use the domain, domain-1, and domain-2 parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain for which the system enabled the DKIM record.
msgstring
The domain's DKIM record status message.
statusinteger
Whether the system enabled the domain's DKIM record on the DNS server. 1 - Enabled. 0 - The system did not enable the domain's DKIM record.
One of: 0 1

ensure_dkim_keys_exist GET#

Validate domains' DKIM private keys

This function confirms the validity of a DomainKeys Identified Mail (DKIM) key for one or more domains.

Notes:

  • If an existing DKIM key does not meet the server's security requirements, the system replaces the existing DKIM key.
  • If no DKIM key exists, the system creates a new key for the domain.
domainstringRequired
The domain for which to confirm a valid DKIM key exists. Note: To check the DKIM key validity for multiple domains, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain for which the system confirmed that a valid DKIM key exists.
msgstring
The domain's DKIM key status message.
statusinteger
Whether the system verified that the domain's DKIM key exists. 1 - The system verified the existence of the domain's DKIM key. 0 - The system did not verify the existence of the domain's DKIM key.
One of: 0 1

fetch_dkim_private_keys GET#

Return domains' DKIM private keys

This function returns a domain's installed DKIM private key in Privacy-Enhanced Mail (PEM) format.

Warning:

We strongly recommend that you protect your private key. If others obtain your private DKIM key, they could sign emails and impersonate you as a sender.

domainstringRequired
The domain for which to retrieve the installed DKIM private key. Note: To retrieve multiple domain DKIM keys, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The queried domain.
pemstring
The domain's DKIM private key, in PEM format.

install_dkim_private_keys GET#

Add domains' DKIM record keys

This function installs existing keys for use in a DomainKeys Identified Mail (DKIM) record. This is useful if you do not want the system to generate keys for DKIM records.

Note:

  • This function does not update the local DNS server's records.
  • If the local DNS server is authoritative for the domain's DNS records, use the UAPI EmailAuth::enable_dkim function to update the local DNS server's DNS records.
  • We recommend that you use the UAPI EmailAuth::install_dkim_private_keys and EmailAuth::enable_dkim functions in a batch UAPI call.
domainstringRequired
The domain for which to install a DKIM private key on the local server. Note: To install multiple RSA private keys for multiple domains, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.
keystringRequired
An RSA key in Privacy-Enhanced Mail (PEM) format. Note: You must provide this parameter for each domain parameter.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The DKIM private key's associated domain.
msgstring
The DKIM private key's installation status message.
statusinteger
Whether the system installed the DKIM private key to the local server. 1 - The system installed the DKIM private key. 0 - The system cannot install the DKIM private key.
One of: 0 1

install_spf_records GET#

Add domains' SPF records

This function installs a Sender Policy Framework (SPF) record for a domain on the DNS server.

domainstringRequired
The domain for which to install an SPF record on the DNS server. Note: To install multiple SPF records, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters.
recordstringRequired
An SPF record. Note: You must provide this parameter for each domain parameter.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The SPF record's associated domain on the DNS server.
msgstring
The SPF record's installation status to the DNS server.
statusinteger
Whether the system installed the SPF record to the DNS server. - 1 - The system installed the SPF record on the DNS server. - 0 - The system cannot install the SPF record on the DNS server.
One of: 0 1

remove_dmarc GET#

Remove DMARC record from domain(s)

This function removes the DMARC record for domains.

domainstringOptional
The domain from which to remove the DMARC record. Note: If you do not include this argument, the system will remove all DMARC records from all domains owned by the user. To remove multiple domain DMARC records, duplicate the parameter name. For example, use the domain=example.com, domain=example2.com, and domain=example3.com parameters. You cannot remove DMARC records on temporary domains.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain for which the DMARC record was removed.
msgstring
Information about the removed DMARC record.
statusinteger
Whether the system removed the domain's DMARC record. 1 - The system removed the domain's DMARC record. 0 - The system did not remove the domain's DMARC record.
One of: 0 1

validate_current_dkims GET#

Validate domains' DKIM records

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

domainstringRequired
The domain for which to check the DKIM records.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The domain that the function used to check the DKIM record. This will be the value of the domain parameter with a default._domainkey prefix.
errorstring
A message that details the reason why the DNS lookup failed. Note: The function only returns this value when the state returned is the ERROR value.
expectedstring
The DKIM record's contents.
recordsarray<object>
The domain's DNS DKIM TXT records. Important: This function may fail to preserve whitespace in DKIM records.
currentstring
The domain's DKIM TXT record data contents. Important: This function may fail to preserve whitespace in DKIM records.
reasonstring
The reason why the DKIM TXT record is not correct, if one exists. Note: This function only returns this value when the state value is PERMFAIL.
statestring
The DKIM TXT record's status: 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.
One of: VALID MISMATCH PERMFAIL
statestring
The domain's DKIM record status. Possible values: 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.
One of: VALID MALFORMED MISMATCH MISSING MULTIPLE NOPUB ERROR
validity_cache_updatestring
The result of the DKIM record's validity cache update operation: 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.
One of: set unset valid invalid none error

validate_current_dmarcs GET#

Validate domains' DMARC records

This function checks the validity of the current DMARC record for one or more domains.

domainstringOptional
The domain for which to check the DMARC record. Note: If you do not include this argument, the system will validate DMARC records for all domains owned by the user.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The target domain of the DMARC policy.
errorstring
A message that details either why the DNS lookup failed, or if there is a SPF/DKIM failure. Note: This will be set to MALFORMED if there is a syntax issue with this domain's SPF and DKIM records.
recordstring
The domain's DMARC TXT record.
statestring
The domain's DMARC record status. Possible values: VALID - A DMARC policy is set for the domain, along with valid SPF and DKIM records for the domain and IP address. MALFORMED - A DMARC record is set, but it did not pass a syntax check. DKIM_SPF_ERROR - A DMARC record exists; however, both the DKIM and SPF records for this domain did not pass validation. DKIM_ERROR - A DMARC record exists; however, the DKIM record for this domain did not pass validation. SPF_ERROR - A DMARC record exists; however, the SPF record for this domain did not pass validation. MISSING - No DMARC record exists for the domain at the DMARC subdomain location. * DNS_ERROR - A DNS error prevented validation of the DMARC record.
One of: VALID MALFORMED DKIM_SPF_ERROR DKIM_ERROR SPF_ERROR MISSING DNS_ERROR
subdomainstring
The domain that the function used to check the DMARC record. This will be the value of the domain parameter with a _dmarc prefix.
suggestedstring
The recommended DMARC policy.

validate_current_ptrs GET#

Validate domains' PTR records

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.

domainstringRequired
The domain for which to validate the PTR records.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

arpa_domainstring
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. 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 function does not return this value for a domain with an invalid IP address.
domainstring
The queried domain.
errorstring
A mmessage that details the reason why the domain's IP address validation failed. Note: The function only returns this value when the state returned is the ERROR value.
helostring
The hostname that the domain uses to identify itself to remote SMTP servers. A valid hostname.
ip_addressstring
The IP address. Note: The function does not return this value for a domain with an invalid IP address.
ip_versioninteger
The IP version number. 4 6 Note: The function does not return this value for a domain with an invalid IP address.
One of: 4 6
nameserversarray<string>
The authoritative nameservers for the domain's PTR record.
ptr_recordsarray<object>
The domain's PTR records. Note: The function does not return this for a domain with an invalid IP address.
domainstring
The fully-qualified domain name (FQDN) that a PTR record points to.
forward_recordsarray<string>
A list of IP addresses that the domain resolves to for A (IPv4) and AAAA (IPv6) records.
statestring
The state of the domain's PTR record. 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.
One of: VALID MISSING_FWD FWD_MISMATCH
statestring
Whether the PTR records are valid for the domain. ERROR - The domain's IP address is invalid. The function returns the reason in the error return. IP_IS_PRIVATE - The IP address exists within a range of private IP addresses. VALID - The PTR record is 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. Note: DNS does not define PTR records for private IP addresses. * The function only returns a VALID response if all of an IP address's PTR records are valid.
One of: ERROR IP_IS_PRIVATE VALID MISSING_PTR PTR_MISMATCH

validate_current_spfs GET#

Validate domains' SPF records

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

domainstringRequired
The domain for which to check the SPF records.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

domainstring
The queried domain.
errorstring
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.
expectedstring
The SPF record for the domain in the DNS.
ip_addressstring
The domain's IP address.
ip_versioninteger
The IP address version. 4 6
One of: 4 6
recordsarray<object>
The SPF records of the domain's DNS.
currentstring
The SPF record's contents.
reasonstring
The reason why the SPF record is not correct, if one exists. Note: If no errors exist, the function does not return this value.
statestring
The SPF record's status: 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. Note: These values correspond with RFC7208 section 2.6.
One of: PASS NEUTRAL FAIL SOFTFAIL TEMPERROR PERMERROR
statestring
The SPF record's status: 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.
One of: VALID MISMATCHED MULTIPLE MISSING ERROR