# cPanel API 2 Functions - Email::changemx Warning: The cPanel API 2 system is deprecated. We **strongly** recommend that you use [UAPI](/cpanel/introduction) instead of cPanel API 2. ## Description This function changes an MX entry's configuration. For more information about MX record settings, read our [Email Routing Configuration](https://docs.cpanel.net/whm/dns-functions/email-routing-configuration/) documentation. br Warning: br We **strongly** recommend that you use the following [UAPI](/cpanel/introduction/) function instead of this function: - `Email::change_mx`— This function creates a Mail Exchanger (MX) record. br div Important: br When you disable the [*DNS* role](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-use-server-profiles/#roles), the system **disables** this function. br ## Examples WHM API (JSON) ```undefined syntaxhighlighter-pre 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="example.com"&exchange="mail.example.com"&oldexchange="mail.example.com"&oldpreference="5"&preference="15"&alwaysaccept="auto" ``` div Note: br For more information, read our [Calls from the WHM API](/whm/use-whm-api-to-call-cpanel-api-and-uapi) documentation. br LiveAPI PHP Class ```undefined syntaxhighlighter-pre $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', ) ); ``` div Note: br For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). br LiveAPI Perl Module ```undefined syntaxhighlighter-pre 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', } ); ``` div Note: br For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system). br cPanel Tag System (deprecated) div Warnings: br - cPanel tags are **deprecated**. We **strongly** recommend that you **only** use the [LiveAPI](/guides/guide-to-the-liveapi-system) system to call the cPanel APIs. Examples are **only** present in order to help developers move from the old cPanel tag system to our [LiveAPI](/guides/guide-to-the-liveapi-system). - cPanel API 2 calls that use cPanel tags vary in code syntax and in their output. - For more information, read our [Deprecated cPanel Tag Usage](/cpanel-api-2/cpanel-api-2-deprecate-cpanel-tag-usage/) documentation. br Command Line ```undefined syntaxhighlighter-pre cpapi2 --user=username Email changemx domain=example.com exchange=mail.example.com preference=15 ``` div Note: br For more information and additional output options, read our [Guide to cPanel API 2](/cpanel-api-2/) documentation or run the `cpapi2 --help` command. br Output (JSON) ```undefined syntaxhighlighter-pre { "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" } } ``` div Note: br Use cPanel's *[API Shell](https://docs.cpanel.net/cpanel/advanced/api-shell-for-cpanel)* interface (*cPanel >> Home >> Advanced >> API Shell*) to directly test cPanel API calls. br ## Parameters table thead tr th strong Parameter th strong Type th strong Description th strong Possible values th strong Example tbody tr td code alwaysaccept td em string td p Whether the mail exchanger accepts mail for its domain. p This parameter defaults to code auto . td ul li code auto — Allow cPanel to determine the appropriate role. li code local — Always accept the domain's mail. li code secondary — Accept mail until a higher priority mail server is available. li code remote — Do not accept mail. td code auto tr td code domain td em string td p strong Required p The mail exchanger's domain. td p A valid domain on the cPanel account. td code example.com tr td code exchange td em string td p strong Required p The mail exchanger's name. td p A valid mail exchanger name. p br td code mail.example.com tr td code oldexchange td em string td p strong Required p The name of an existing mail exchanger. p br td A valid mail exchanger on the cPanel account. td code mail.example.com tr td code oldpreference td em integer td div p The code oldexchange exchanger's a priority value . p {% admonition type="info" name="Note:" %} {% /admonition %} p If multiple MX entries match the code oldexchange value, the system uses this parameter to find the correct entry. td A positive integer. td code 5 tr td code preference td em integer td p strong Required p The mail exchanger's a priority value . td div p A positive integer. Note: p Common practice recommends that you set the priority value to a number divisible by five. td code 15 ## Returns table thead tr th strong Return th strong Type th strong Description th strong Possible values th strong Example tbody tr td code statusmsg td em string td A message of success or a reason for failure. td ul li A message of success that includes the domain name and server name. li A string that describes an error. td div code Replacing existing entry on line matched old entry and old priority: 25:\nBind reloading on server1 using rndc zone: [example.com]\n tr td code status td em Boolean td Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1 tr td code checkmx td em hash td A hash of the mail exchanger's data. td This hash includes the code warnings , code issecondary , code local , code detected , code remote , code isprimary , code changed , code secondary , and code mxcheck returns. td br tr td p code warnings td em string td p Warning messages, if any exist. p The function returns this value in the code checkmx hash. td One or more warning messages. td div code Auto Detect of MX configuration not possible due to non-resolving MX entries. Defaulting to last known setting: local. tr td p code issecondary td p em Boolean td p Whether the mail exchanger is a secondary exchanger. p The function returns this value in the code checkmx hash. td ul li code 1 — Secondary. li code 0 — Not secondary. td p code 0 tr td p code local td em Boolean td p Whether the mail exchanger is a local exchanger. p The function returns this value in the code checkmx hash. td ul li code 1 — Local. li code 0 — Not local. td code 0 tr td p code detected td em string td p The mail exchanger type. p The function returns this value in the code checkmx hash. td ul li code auto li code local li code secondary li code remote td code auto tr td p code remote td em Boolean td p Whether the mail exchanger is a remote exchanger. p The function returns this value in the code checkmx hash. td ul li code 1 — Remote. li code 0 — Not remote. td code 0 tr td p code isprimary td em Boolean td p Whether the mail exchanger is the primary mail exchanger. p The function returns this value in the code checkmx hash. td ul li code 1 — Primary. li code 0 — Not primary. td code 0 tr td p code changed td em Boolean td p Whether a change occurred during the function. p The function returns this value in the code checkmx hash. td ul li code 1 — Change occurred. li code 0 — No change. td code 1 tr td p code secondary td em Boolean td p Whether the mail exchanger is a secondary exchanger. p The function returns this value in the code checkmx hash. td ul li code 1 — Secondary. li code 0 — Not secondary. td p code 0 tr td p code mxcheck td em string td p The mail exchanger type. p The function returns this value in the code checkmx hash. td ul li code auto li code local li code secondary li code remote td code auto tr td code results td em string td A message of success or a reason for failure. td ul li A message of success that includes the domain name and server name. li A string that describes an error. td div code Replacing existing entry on line matched old entry and old priority: 25:\nBind reloading on server1 using rndc zone: [example.com]\n tr td code reason td em string td div p A reason for failure. Note: p This function only returns a code reason value if it failed. td p A string that describes the error. td code This is an error message. tr td code result td em Boolean td p Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1