# cPanel API 2 Functions - Email::listmxs 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 lists mail exchangers. For more information about MX record settings, read our [Email Routing Configuration](https://docs.cpanel.net/whm/dns-functions/email-routing-configuration/) documentation. Warning: We **strongly** recommend that you use the following [UAPI](/cpanel/introduction/) function instead of this function: - `Email::list_mxs ` — This function lists Mail Exchanger (MX) records. div Important: br When you disable the [*Receive Mail* role](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-use-server-profiles/#roles), the system **disables** this function. br div Note: br This function is identical to the cPanel API 2 ` Email::listmx` 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=listmxs&domain="example.com" ``` 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. // List the mail exchangers for example.com. $list_all_mxs = $cpanel->api2( 'Email', 'listmxs', array( 'user' => 'user', 'domain' => 'example.com', ) ); ``` 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. # List the mail exchangers for example.com. my $list_all_mxs = $cpliveapi->api2( 'Email', 'listmxs', { 'user' => 'user', 'domain' => 'example.com', } ); ``` 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 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 listmxs user=user domain=example.com ``` div Notes: br - You **must** URI-encode values. - `username` represents your account-level username. - You **must** run the `--user=username` command. - For more information and additional output options, read our [Guide to cPanel API 2](/cpanel-api-2/) documentation or run the `cpapi2 --help` command. - If you run CloudLinux™, you **must** use the full path of the `cpapi2` command: ```undefined syntaxhighlighter-pre /usr/local/cpanel/bin/cpapi2 ``` br Output (JSON) ```undefined syntaxhighlighter-pre { "cpanelresult": { "apiversion": 2, "func": "listmxs", "data": [ { "statusmsg": "Fetched MX List", "status": 1, "entries": [ { "priority": "0", "mx": "mail.example.com", "domain": "example.com", "entrycount": 1, "row": "odd" }, { "priority": "7", "mx": "mail2.example.com", "domain": "example.com", "entrycount": 2, "row": "even" }, { "priority": "15", "mx": "mail6.example.com", "domain": "example.com", "entrycount": 3, "row": "odd" } ], "local": 1, "remote": 0, "detected": "local", "mx": "mail", "domain": "example.com", "mxcheck": "auto", "secondary": 0, "alwaysaccept": 0 } ], "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 user td em string td p strong Required p The cPanel account's username. td A valid username on the cPanel account. td code user tr td code domain td em string td p The domain to query. p If you do not use this parameter, the function returns a list of all mail exchangers on the cPanel account. td p A valid domain on the cPanel account. td code example.com ## 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 code Fetched MX List li A string that describes an error. td p code Fetched MX List 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 entries td em array of hashes td An array of hashes of a domain's mail exchangers. td Each hash contains the code priority , code mx , code domain , code entrycount , and code row returns. td br tr td p code priority td em integer td p The mail exchanger's a priority value . p The function returns this value in the code entries hash. td A positive integer. td p code 5 tr td p code mx td p em string td p The mail exchanger name. p The function returns this value in the code entries hash. td p A valid mail exchanger on the domain or cPanel account. td p code mail.example.com tr td p code domain td em string td p The mail exchanger's domain. p The function returns this value in the code entries hash. td p A valid domain on the cPanel account. td code example.com tr td p code entrycount td em integer td p The mail exchanger's order in the list of priorities. p The function returns this value in the code entries hash. td p A positive integer. p For example, the mail exchanger with the highest priority returns code 1 , and the next highest priority returns code 2 . td code 1 tr td p code row td em string td p Whether the mail exchanger is an odd or an even entry. p The function returns this value in the code entries hash. td ul li code odd li code even td code odd tr td code local td em Boolean td Whether the domain's highest-priority mail exchanger is a local mail exchanger. td ul li code 1 — Local. li code 0 — strong Not local. td p code 1 tr td code remote td em Boolean td Whether the domain's highest-priority mail exchanger is remote. td ul li code 1 — Remote. li code 0 — strong Not remote. td code 0 tr td code detected td em string td The domain's highest-priority mail exchanger's type. td ul li code auto li code local li code remote li code secondary td code auto tr td code mx td em string td The domain's highest-priority mail exchanger's name. td A valid mail exchanger on the domain or cPanel account. td code mail.example.com tr td code domain td em string td The domain. td A valid domain on the cPanel account. td code example.com tr td code mxcheck td em string td The domain's highest-priority mail exchanger's type. td ul li code auto li code local li code remote li code secondary td code auto tr td code secondary td em Boolean td Whether the domain's highest-priority mail exchanger is secondary. td ul li code 1 — Secondary. li code 0 — strong Not secondary. td code 0 tr td code alwaysaccept td em Boolean td Whether the domain's highest-priority mail exchanger accepts local mail. td ul li code 1 — Accept local mail. li code 0 — Does strong not accept local mail. td code 1 tr td code reason td em string td div p A reason for failure. p div Note: br p This function strong only returns a code reason value if it failed. br 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