UAPI Functions - Email::change_mx - Knowledgebase

Description

This function modifies a Mail Exchanger (MX) record. For more information about MX record settings, read our Edit MX Entry documentation.

Examples

cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Email/change_mx?domain=example.com&exchanger=mail.example.com&oldexchanger=mail.example.com&preference=15&oldpreference=5&alwaysaccept=local

 LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Update the mail.example.com MX record.
$update_mx = $cpanel->uapi(
    'Email', 'change_mx',
    array(
        'domain'        => 'example.com',
        'exchanger'     => 'mail.example.com',
        'oldexchanger'  => 'mail.example.com',
        'preference'    => '15',
        'oldpreference' => '5',
        'alwaysaccept'  => 'local',
         )
);

 LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Update the mail.example.com MX record.
my $update_mx = $cpliveapi->uapi(
    'Email', 'change_mx',
    {
        'domain'        => 'example.com',
        'exchanger'     => 'mail.example.com',
        'oldexchanger'  => 'mail.example.com',
        'preference'    => '15',
        'oldpreference' => '5',
        'alwaysaccept'  => 'local',
    }
);

 cPanel Template Toolkit

<!-- Update the mail.example.com MX record, then display the changed value. -->
[% data = execute( 'Email', 'change_mx', { 'domain' => 'example.com', 'exchanger' => 'mail.example.com', 'oldexchanger'  => 'mail.example.com', 'preference' => '15', 'oldpreference' => '5', 'alwaysaccept' => 'local', } ); %]
[% FOREACH q = data.checkmx.changed %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the changed value. -->
[% execute('Email', 'change_mx', { 'domain' => 'example.com', 'exchanger' => 'mail.example.com', 'oldexchanger'  => 'mail.example.com', 'preference' => '15', 'oldpreference' => '5', 'alwaysaccept' => 'local', } ).data.checkmx.changed %]

Command Line

uapi --user=username Email change_mx domain=example.com exchanger=mail.example.com oldexchanger=mail.example.com preference=15 oldpreference=5 alwaysaccept=local

Notes:

You must URI-encode values.
username represents your account-level username.

Output (JSON)

{

"messages":null,

"errors":null,

"status":1,

"metadata":{

},

"data":{

"statusmsg":"Replacing existing entry on line matched old entry and old priority: 51:\nBind reloading on example using rndc zone: [example.com]\n",

"checkmx":{

"warnings":[

],

"issecondary":0,

"local":1,

"remote":0,

"detected":"local",

"isprimary":1,

"changed":1,

"mxcheck":"local",

"secondary":0

},

"status":1,

"results":"Replacing existing entry on line matched old entry and old priority: 51:\nBind reloading on example using rndc zone: [example.com]\n"

}

Note:

Use cPanel's API Shell interface (Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Parameter	Type	Description	Possible values	Example
domain	string	Required The mail exchanger's domain.	A valid domain on the account.	example.com
exchanger	string	Required The mail exchanger's name.	A valid mail exchanger name.	mail.example.com
oldexchanger	string	The mail exchanger's current name. If you do not use this parameter, the function creates a new MX record.	The name of an existing mail exchanger.	mail.example.com
preference	integer	Required The mail exchanger's new priority value.	A positive integer. Note: Common practice sets a priority value divisible by five.	15
oldpreference	integer	The mail exchanger's current priority value. If multiple MX entries match the oldexchangervalue, the system uses this parameter to find the correct entry.	The existing mail exchanger's current priority value.	5
alwaysaccept	string	Whether the mail exchanger accepts all mail for the domain.	auto local secondary remote	1

Returns

Return	Type	Description	Possible values	Example
statusmsg	string	A message of success, or an error message.	A message of success that begins with Added entry:. An error message.
checkmx	hash	A hash of the mail exchanger's data.	This hash includes the warnings, issecondary, local,detected, remote, isprimary, changed, secondary, andmxcheck returns.
warnings	array	Warning messages, if any exist. The function returns this value in the checkmx hash.	One or more warning messages.
issecondary	Boolean	Whether the mail exchanger is a secondary exchanger. The function returns thisvalue in the checkmx hash.	1 — Secondary. 0 — Not secondary.	0
local	Boolean	Whether the mail exchanger is a local exchanger. The function returns thisvalue in the checkmx hash.	1 — Local. 0 — Not local.	0
detected	string	The mail exchanger type. The function returns thisvalue in the checkmx hash.	auto local secondary remote	auto
remote	Boolean	Whether the mail exchanger is a remote exchanger. The function returns thisvalue in the checkmx hash.	1 — Remote. 0 — Not remote.	0
isprimary	Boolean	Whether the mail exchanger is the primary mail exchanger. The function returns thisvalue in the checkmx hash.	1 — Primary. 0 — Not primary.	0
changed	Boolean	Whether a change occurred during the function. The function returns thisvalue in the checkmx hash.	1 — Change occurred. 0 — No change.	1
secondary	Boolean	Whether the mail exchanger is a secondary exchanger. The function returns thisvalue in the checkmx hash.	1 — Secondary. 0 — Not secondary.	0
mxcheck	string	The mail exchanger type. The function returns thisvalue in the checkmx hash.	auto local secondary remote	auto
status	Boolean	Whether the function succeeded.	1 — Success. 0 — Failure.	1
results	string	A message of success, or an error message.	A message of success that begins with Added entry:. An error message.

Knowledgebase

Categories

Categories