You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • UAPI Functions - Email::list_pops
Skip to end of metadata
Go to start of metadata

Description

This function lists the cPanel account's email accounts.

Important:

In cPanel & WHM version 76 and later, when you disable the Receive Mail role, the system disables this function.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/list_pops?regex=user


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all email addresses that contain "user".
$emails = $cpanel->uapi(
    'Email', 'list_pops',
    array(
        'regex'      => 'user',
        )
);


Note:

For more information, read our Guide to the LiveAPI System.


 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# List all email addresses that contain "user".
my $emails = $cpliveapi->uapi(
    'Email', 'list_pops',
    {
        'regex'      => 'user',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.


 Command Line
uapi --user=username Email list_pops regex=user


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"data": [{
		"suspended_incoming": 0,
		"suspended_login": 0,
		"login": "example1@example.com",
		"email": "example1@example.com"
	}, {
		"login": "example2@example.com",
		"suspended_login": 0,
		"suspended_incoming": 0,
		"email": "example2@example.com"
	}, {
		"login": "example3@example.com",
		"suspended_login": 0,
		"suspended_incoming": 0,
		"email": "example3@example.com"
	}],
	"warnings": null,
	"messages": null,
	"metadata": {
		"transformed": 1
	},
	"status": 1,
	"errors": null
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
regexstring

A Perl Compatible Regular Expression (PCRE) that filters the results.

A valid PCRE.

user
no_validateBoolean

Whether to skip the email database's validation check.

This parameter defaults to 0.

  • 1 — Skip the validation check.
  • 0 — Run the validation check.
1
skip_mainBoolean

Whether to exclude the cPanel account's main account from the results.

This parameter defaults to 0.

  • 1 — Exclude the main account.
  • 0 — Include the main account.
0

Returns

ReturnTypeDescriptionPossible valuesExample

array of hashesA hash of data for an email address on the cPanel account.Each hash includes the email, login, suspended_login, and suspended_incoming returns.

email

string

An email address.

The function includes this value in the unnamed hash for each email address.

  • A valid email address on the cPanel account.
  • The cPanel account username, for the main account.

user@example.com

login

string

The email account login.

The function includes this value in the unnamed hash for each email address.

  • A valid email address on the cPanel account.
  • Main Account, for the main account.
user@example.com

suspended_login

Boolean

Whether logins for the email account are suspended.

Note:

We added this return in cPanel & WHM version 11.54

The function includes this value in the unnamed hash for each email address.

  • 1 — Suspended.
  • 0 — Not suspended.
0

suspended_incoming

Boolean

Whether incoming email for the email account is suspended.

Note:

We added this return in cPanel & WHM version 11.54

The function includes this value in the unnamed hash for each email address.

  • 1 — Suspended.
  • 0 — Not suspended.
0