UAPI Functions - Email::add_mx - Knowledgebase

Description

This function creates 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/add_mx?domain=example.com&exchanger=mail.example.com&preference=5&alwaysaccept=1

 LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Create the mail.example.com MX record.
$new_mx = $cpanel->uapi(
    'Email', 'add_mx',
    array(
        'domain'        => 'example.com',
        'exchanger'     => 'mail.example.com',
        'preference'    => '5',
        'alwaysaccept'  => '1',
         )
);

 LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Create the mail.example.com MX record.
my $new_mx = $cpliveapi->uapi(
    'Email', 'add_mx',
    {
        'domain'        => 'example.com',
        'exchanger'     => 'mail.example.com',
        'preference'    => '5',
        'alwaysaccept'  => '1',
    }
);

 cPanel Template Toolkit

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

Command Line

uapi --user=username Email add_mx domain=example.com exchanger=mail.example.com preference=5 alwaysaccept=1

Notes:

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

 Output (JSON)

{ 
   "messages":null,
   "errors":null,
   "status":1,
   "data":{ 
      "statusmsg":"Added entry:\nBind reloading on example using rndc zone: [example.com]\n",
      "checkmx":{ 
         "warnings":[
         ],
         "issecondary":0,
         "local":1,
         "remote":0,
         "detected":"local",
         "isprimary":1,
         "changed":0,
         "mxcheck":"auto",
         "secondary":0,
         "status":1,
         "results":"Added entry:\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 new mail exchanger's domain.	A valid domain on the account.	example.com
exchange , newmx , or exchanger	string	Required The new mail exchanger's name.	A valid mail exchanger name.	mail.example.com
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.	5
alwaysaccept	Boolean	Whether the mail exchanger accepts all mail for the domain. This value defaults to 0.	1 — The mail exchanger always accepts mail. 0 — The mail exchanger does notalways accept mail.	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 this value in the checkmx hash.	1 — Secondary. 0 — Not secondary.	0
local	Boolean	Whether the mail exchanger is a local exchanger. The function returns this value in the checkmx hash.	1 — Local. 0 — Not local.	0
detected	string	The mail exchanger type. The function returns this value in the checkmx hash.	auto local secondary remote	auto
remote	Boolean	Whether the mail exchanger is a remote exchanger. The function returns this value in the checkmx hash.	1 — Remote. 0 — Not remote.	0
isprimary	Boolean	Whether the mail exchanger is the primary mail exchanger. The function returns this value in the checkmx hash.	1 — Primary. 0 — Not primary.	0
changed	Boolean	Whether a change occurred during the function. The function returns this value in the checkmx hash.	1 — Change occurred. 0 — No change.	1
secondary	Boolean	Whether the mail exchanger is a secondary exchanger. The function returns this value in the checkmx hash.	1 — Secondary. 0 — Not secondary.	0
mxcheck	string	The mail exchanger type. The function returns this value 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

UAPI Functions - Email::add_mx

Description

Examples

Parameters

Returns

Related Articles

Support

Knowledgebase

Categories

Categories

UAPI Functions - Email::add_mx

Description

Examples

Parameters

Returns

Related Articles

Support

Generate Password