Description
This function changes an MX entry's configuration.
Warning:
We strongly recommend that you use the following UAPI function instead of this function:
-
Email::change_mx— This function modifies a Mail Exchanger (MX) record.
Examples
https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=changemx&domain=
$cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Update settings for mail.example.com.$update_mx = $cpanel->api2( 'Email', 'changemx', array( 'alwaysaccept' => 'auto', 'domain' => 'example.com', 'exchange' => 'mail.example.com', 'oldexchange' => 'mail.example.com', 'oldpreference' => '5', 'preference' => '15', ) );my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Update settings for mail.example.com.my $update_mx = $cpliveapi->api2( 'Email', 'changemx', { 'alwaysaccept' => 'auto', 'domain' => 'example.com', 'exchange' => 'mail.example.com', 'oldexchange' => 'mail.example.com', 'oldpreference' => '5', 'preference' => '15', });Warning:
In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.
cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
cpapi2 --user=username Email changemx domain=example.com exchange=mail.example.com preference=15
{ "cpanelresult": { "apiversion": 2, "func": "changemx", "data": [ { "statusmsg": "Replacing existing entry on line matched old entry and old priority: 25:\nBind reloading on server1 using rndc zone: [example.com]\n", "status": 1, "checkmx": { "warnings": [ ], "issecondary": 0, "local": 0, "detected": "local", "remote": 0, "isprimary": 1, "changed": 0, "secondary": 0, "mxcheck": "auto" }, "results": "Replacing existing entry on line matched old entry and old priority: 25:\nBind reloading on server1 using rndc zone: [example.com]\n" } ], "event": { "result": 1 }, "module": "Email" }}Note:
Use cPanel's API Shell interface (Home >> Advanced >> API Shell) to directly test cPanel API calls.
Parameters
|
Parameter |
Type |
Description |
Possible values |
Example |
|
alwaysaccept |
string |
Whether the mail exchanger accepts mail for its domain. This parameter defaults to auto. |
|
auto |
|
domain |
string |
Required The mail exchanger's domain. |
A valid domain on the cPanel account. |
example.com |
|
exchange |
string |
Required The mail exchanger's name. |
A valid mail exchanger name.
|
mail.example.com |
|
oldexchange |
string |
The name of an existing mail exchanger. Note: If you do not use this parameter, the function creates a new mail exchanger. |
A valid mail exchanger on the cPanel account. |
mail.example.com |
|
oldpreference |
integer |
The oldexchange exchanger'spriority value. Note: If multiple MX entries match the oldexchange value, the system uses this parameter to find the correct entry. |
A positive integer. |
5 |
|
preference |
integer |
Required The mail exchanger's priority value. |
A positive integer. Note: Common practice recommends that you set the priority value to a number divisible by five. |
15 |
Returns
|
Return |
Type |
Description |
Possible values |
Example |
|
statusmsg |
string |
A message of success or a reason for failure. |
|
|
|
status |
Boolean |
Whether the function succeeded. |
|
1 |
|
checkmx |
hash |
A hash of the mail exchanger's data. |
This hash includes the warnings, issecondary,local, detected, remote, isprimary, changed,secondary, and mxcheck returns. |
|
|
warnings |
string |
Warning messages, if any exist. The function returns this value in thecheckmx hash. |
One or more warning messages. |
|
|
issecondary |
Boolean |
Whether the mail exchanger is a secondary exchanger. The function returns this value in thecheckmx hash. |
|
0 |
|
local |
Boolean |
Whether the mail exchanger is a local exchanger. The function returns this value in thecheckmx hash. |
|
0 |
|
detected |
string |
The mail exchanger type. The function returns this value in thecheckmx hash. |
|
auto |
|
remote |
Boolean |
Whether the mail exchanger is a remote exchanger. The function returns this value in thecheckmx hash. |
|
0 |
|
isprimary |
Boolean |
Whether the mail exchanger is the primary mail exchanger. The function returns this value in thecheckmx hash. |
|
0 |
|
changed |
Boolean |
Whether a change occurred during the function. The function returns this value in thecheckmx hash. |
|
1 |
|
secondary |
Boolean |
Whether the mail exchanger is a secondary exchanger. The function returns this value in thecheckmx hash. |
|
0 |
|
mxcheck |
string |
The mail exchanger type. The function returns this value in thecheckmx hash. |
|
auto |
|
results |
string |
A message of success or a reason for failure. |
|
|
|
reason |
string |
A reason for failure. Note: This function only returns areason value if it failed. |
A string that describes the error. |
This is an error message. |
|
result |
Boolean |
Whether the function succeeded. |
|
1 |