cPanel API 2 Functions - Email::listmxs

Description

This function lists mail exchangers. For more information about MX record settings, read our Edit MX Entry documentation.

Warning:

We strongly recommend that you use the following UAPI function instead of this function:

  • Email::list_mxs — This function lists Mail Exchanger (MX) records.

Note:

This function is identical to the cPanel API 2 Email::listmx function. 

 

Examples 


 WHM API (JSON)

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=

 LiveAPI PHP Class

$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'
    
);

 LiveAPI Perl Module

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',
    }
);

 cPanel Tag System (deprecated)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.

 

 Command Line

cpapi2 --user=username Email listmxs user=user domain=example.com

 

Notes:

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

 Output (JSON)

{
  "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"
  }
}

Note:

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

 

Parameters

 Parameter 

 Type

Description

Possible values

Example

 user

 string

 Required

 The cPanel account's username.

 A valid username on the cPanel account. 

 user

 domain

 string 

 The domain to query.

 If you do not use this parameter, the function returns a list of all mail exchangers on the cPanel account. 

 A valid domain on the cPanel account.

 example.com 

 

Returns

Return

Type

Description

Possible values

Example

 statusmsg

 string

 A message of success or a reason for failure.

  • Fetched MX List  
  • A string that describes an error.

 Fetched MX List

 status

 Boolean

 Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.

 1

 entries

 array of hashes 

 An array of hashes of a domain's mail exchangers.

 Each hash contains the priority,mx, domain, entrycount, and rowreturns.

  

 priority

 integer

 The mail exchanger'spriority value.

 The function returns this value in the entries hash.

 A positive integer.

 5

 mx

 string

 The mail exchanger name.

 The function returns this value in the entries hash.

 A valid mail exchanger on the domain or cPanel account.

 mail.example.com

 domain

 string

 The mail exchanger's domain.

 The function returns this value in the entries hash.

 A valid domain on the cPanel account.

 example.com

 entrycount

 integer

 The mail exchanger's order in the list of priorities.

 The function returns this value in the entries hash.

 A positive integer.

 For example, the mail exchanger with the highest priority returns 1, and the next highest priority returns 2.

 1

 row

 string

 Whether the mail exchanger is an odd or an even entry.

 The function returns this value in the entries hash.

  • odd
  • even

 odd

 local

 Boolean

 Whether the domain's highest-priority mail exchanger is a local mail exchanger.

  • 1 — Local.
  • 0 — Not local.

 1

 remote

 Boolean

 Whether the domain's highest-priority mail exchanger is remote.

  • 1 — Remote.
  • 0 — Not remote.

 0

 detected

 string

 The domain's highest-priority mail exchanger'stype.

  • auto
  • local
  • remote
  • secondary

 auto

 mx

 string

 The domain's highest-priority mail exchanger's name.

 A valid mail exchanger on the domain or cPanel account.

 mail.example.com

 domain

 string

 The domain.

 A valid domain on the cPanel account.

 example.com

 mxcheck

 string

 The domain's highest-priority mail exchanger'stype.

  • auto
  • local
  • remote
  • secondary

 auto

 secondary

 Boolean

 Whether the domain's highest-priority mail exchanger is secondary.

  • 1 — Secondary.
  • 0 — Not secondary.

 0

 alwaysaccept 

 Boolean

 Whether the domain's highest-priority mail exchanger accepts local mail.

  • 1 — Accept local mail.
  • 0 — Does not accept local mail.

 1

 reason

 string

 A reason for failure.

 Note:

 This function only returns a reasonvalue if it failed. 

 A string that describes the error.

 This is an error message. 

 result

 Boolean

 Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.

 1

    

  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....