Description
This function creates an MX record. For more information about MX record settings, read our Edit MX Entry documentation.
Warning:
We strongly recommend that you use the following UAPI function instead of this function:
-
Email::add_mx— This function creates 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=addmx&domain=
$cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Replace mail.example.com with an MX entry for newmx.example.com.$add_new_mx = $cpanel->api2( 'Email', 'addmx', array( 'alwaysaccept' => 'auto', 'domain' => 'example.com', 'exchange' => 'newmx.example.com', 'oldexchange' => 'mail', 'oldpreference' => '5', 'preference' => '15', ) );my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Replace mail.example.com with an MX entry for newmx.example.com.my $add_new_mx = $cpliveapi->api2( 'Email', 'addmx', { 'alwaysaccept' => 'auto', 'domain' => 'example.com', 'exchange' => 'newmx.example.com', 'oldexchange' => 'mail', '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 addmx domain=example.com exchange=newmx.example.com oldexchange=mail oldpreference=5 preference=15 alwaysaccept=auto
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 new mail exchanger's domain. |
A valid domain on the cPanel account. |
example.com |
|
exchange,newmx, orexchanger |
string |
Required The new mail exchanger's name. |
A valid mail exchanger name. |
newmx.example.com |
|
oldexchange,oldmx, oroldexchanger |
string |
Required The name of an existing mail exchanger, which the new exchanger replaces. |
A valid mail exchanger on the cPanel account. |
|
|
oldpreferenceor oldpriority |
integer |
Required The oldexchange exchanger's priority value. If multiple MX entries match theoldexchange value, the system uses this parameter to find the correct entry. |
A positive integer. |
5 |
|
preference orpriority |
integer |
Required The new mail exchanger's priority value. |
A positive integer. Note: It is common practice to set a priority value that is 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 |