# cPanel API 2 Functions - Email::addmx 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 creates an MX record. For more information about MX record settings, read our [Email Routing Configuration](https://docs.cpanel.net/whm/dns-functions/email-routing-configuration/) documentation. div Warning: br We **strongly** recommend that you use the following [UAPI](/cpanel/introduction/) function instead of this function: - ` Email::add_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=addmx&domain="example.com"&exchange="newmx.example.com"&oldexchange="oldmail"&oldpreference="1"&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. // 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', ) ); ``` 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. # 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', } ); ``` 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 addmx domain=example.com exchange=newmx.example.com oldexchange=mail oldpreference=5 preference=15 alwaysaccept=auto ``` 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": "addmx", "data": [ { "statusmsg": "Added entry: example.com.\tIN\tMX\t0\tnewmx.\n\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": "Added entry: example.com.\tIN\tMX\t0\tnewmx.\n\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 . p br 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 new mail exchanger's domain. td p A valid domain on the cPanel account. td code example.com tr td code exchange , code newmx , or code exchanger td em string td p strong Required p The new mail exchanger's name. td p A valid mail exchanger name. td code newmx.example.com tr td code oldexchange , code oldmx , or code oldexchanger td em string td p strong Required p The name of an existing mail exchanger, which the new exchanger replaces. td A valid mail exchanger on the cPanel account. td code mail tr td code oldpreference or code oldpriority td em integer td p strong Required p The code oldexchange exchanger's a priority value . 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 or code priority td em integer td p strong Required p The new mail exchanger's a priority value . td div p A positive integer. Note: p It is common practice to set a priority value that is 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 mail exchanger, domain, and server name. li A string that describes an error. td div code Added entry: example.com.\tIN\tMX\t0\tnewmx.\n\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 mail exchanger, domain, and server name. li A string that describes an error. td div code Added entry: example.com.\tIN\tMX\t0\tnewmx.\n\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