If you ever tried updating the MX record in cPanel only to be greeted with an error with something like “The DNS zone file is invalid”, here’s something you can try.
For me, the full error was:
“Error: The DNS zone file is invalid. (Line 10: NS record ‘10.255.250.30.’ appears to be an address; Line 11: NS record ‘10.255.251.30.’ appears to be an address)”
Before you continue, please note that the following instructions can be a bit technical, and you will need to know how to use the terminal and be familiar with commands like curl. If you are reading this page looking to change MX records within cPanel and not on your regular domain name provider’s DNS zone, then we assume you are fairly tech-savvy already. 😉
The Problem
When you see the error above, it usually means that the DNS records stored in the server are corrupt or have invalid data. These records are called the “DNS zone file”. The Zone Editor of cPanel will not let you continue modifying any other records if for any reason the zone file is invalid.
The Solution
To fix this problem, we can modify the values directly through the cPanel API.
Authentication
To access the API, you will need a “security token. This can be an API key, or your session ID after logging into cPanel. If you already have access or are familiar with the cPanel API, you may skip this section.
Retrieving your session ID
Your session ID can be found after logging into cPanel in the URL. Take the following URL for example:
https://example.com:2083/cpsess5732092450/frontend/jupiter/index.htmlThe session ID will be cpsess5732092450
Alternatively, create an API Token
- Login to cPanel
- Go to
Manage API Tokens - Click
+ Create - Give your token a name.
- Click
+ Create - A token will be generated looking like a string of upper case characters and numbers. Make a note of the API token, you won’t be able to see it again!
- Keep the token somewhere safe. This token will allow access to your server, which attackers can use to get your information, change values, and install viruses.
Accessing the cPanel API
To access the cPanel API, we use HTTP(s) requests. The examples use the curl command, but you can use any flavour of tools to make requests you like. With either the session ID or the API token you have, choose one of the commands below to execute. These commands return the MX records of the specified domain. Replace YOUR_SESSION_ID, CPANEL_USERNAME, and YOUR_API_TOKEN as appropriate.
curl 'https://example.com:2083/YOUR_SESSION_ID/execute/Email/list_mxs?domain=example.com'curl -H 'Authorization: cpanel CPANEL_USERNAME:YOUR_API_TOKEN' 'https://example.com:2083/execute/Email/list_mxs?domain=example.com'Take note of the existing exchanger record, which will be needed when updating later on.
Updating the MX record
The following command will update your DNS mail exchanger record. Make sure you update the parameters to suit your needs. The domain, exchanger, oldexchanger, and priority parameters in the URL query string can be updated.
curl -H 'Authorization: cpanel CPANEL_USERNAME:YOUR_API_TOKEN' 'https://example.com:2083/execute/Email/change_mx?domain=example.com&exchanger=newdomain.com&oldexchanger=olddomain.com&priority=0'For more commands, such as adding or deleting MX records, or anything else to do with cPanel, check out the links in the resources section.
Bonus Content
Some extra commands that can be executed are:
https://example.com:2083/execute/Email/trace_delivery?recipient=email@example.com
https://example.com:2083/execute/Email/unset_manual_mx_redirects?domain=example.com
https://example.com:2083/execute/Email/set_manual_mx_redirects?domain=example.com&mx_host=newmx.example.comQuestions?
Leave a comment if you have any questions or comments. If you see any errors or have better ways to do this, please let us know!
Resources
- General cPanel API docs: https://api.docs.cpanel.net/cpanel/introduction/
- List MX records docs: https://api.docs.cpanel.net/openapi/cpanel/operation/list_mxs/
- Change MX record docs: https://api.docs.cpanel.net/openapi/cpanel/operation/change_mx/