Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function lists the cPanel account's email accounts with disk information.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/list_pops_with_disk?domain=example.com&maxaccounts=500&no_validate=1&regex=%2F%5E%5Ba-z0-9_-%5D%7B6%2C18%7D%24%2F&email=user&infinitylang=0


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 email accounts and disk information with a username between 8-16 characters.
$emails = $cpanel->uapi(
    'Email', 'list_pops_with_disk',
    array(
        'domain'       => 'example.com',
        'maxaccounts'  => '500',
        'no_validate'  => '1',
        'regex'        => '/^[a-z0-9_-]{6,18}$/',
        'email'        => 'user@example.com',
        'infinitylang' => '0'
        )
);

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 email accounts and disk information with a username between 8-16 characters.
my $emails = $cpliveapi->uapi(
    'Email', 'list_pops_with_disk',
    {
        'domain'       => 'example.com',
        'maxaccounts'  => '500',
        'no_validate'  => '1',
        'regex'        => '/^[a-z0-9_-]{6,18}$/',
        'email'        => 'user@example.com',
        'infinitylang' => '0'
    }
);

Note:

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

 cPanel Template Toolkit
<!-- Get a hash of email accounts, then display the email only. -->
[% data = execute('Email', 'list_pops_with_disk', { 'domain' => 'example.com', 'maxaccounts' => '500', 'no_validate' => '1', 'regex' => '/^[a-z0-9_-]{6,18}$/', 'email' => 'user@example.com', 'infinitylang' => '0' } ) %]
[% FOREACH q = data.email %]
     <p>
         [% q %]
     </p>
[% END %]
    
<!-- Get only the email addresses. -->
[% execute('Email', 'list_pops_with_disk', { 'domain' => 'example.com', 'maxaccounts' => '500', 'no_validate' => '1', 'regex' => '/^[a-z0-9_-]{6,18}$/', 'email' => 'user@example.com', 'infinitylang' => '0' } ).data.email %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username Email list_pops_with_disk domain=example.com maxaccounts=500 no_validate=1 regex=/^[a-z0-9_-]{6,18}$/ email=user%40example.com infinitylang=0

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. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)
{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  
      "transformed":1
   },
   "data":[  
      {  
         "txtdiskquota":"unlimited",
         "diskquota":"unlimited",
         "diskusedpercent":0,
         "mtime":1415894498,
         "diskused":0,
         "humandiskquota":"None",
         "_diskused":"483",
         "login":"user@example.com",
         "email":"user@example.com",
         "domain":"example.com",
         "user":"user",
         "suspended_incoming":0,
         "suspended_login":0,
         "diskusedpercent20":0,
		 "diskusedpercent_float":0,
         "humandiskused":"483 bytes",
         "_diskquota":0
      },
      {  
         "txtdiskquota":"unlimited",
         "diskquota":"unlimited",
         "diskusedpercent":0,
         "mtime":1415894498,
         "diskused":0,
         "humandiskquota":"None",
         "_diskused":"0",
         "login":"mailacct@example.com",
         "email":"mailacct@example.com",
         "domain":"example.com",
         "user":"mailacct",
         "suspended_incoming":0,
         "suspended_login":0,
         "diskusedpercent20":0,
		 "diskusedpercent_float":0,
         "humandiskused":"None",
         "_diskquota":0
      },
      {  
         "txtdiskquota":"unlimited",
         "diskquota":"unlimited",
         "diskusedpercent":0,
         "mtime":1415894498,
         "diskused":0,
         "humandiskquota":"None",
         "_diskused":"0",
         "login":"another@example.com",
         "email":"another@example.com",
         "domain":"example.com",
         "user":"another",
         "suspended_incoming":0,
         "suspended_login":0,
         "diskusedpercent20":0,
		 "diskusedpercent_float":0,
         "humandiskused":"None",
         "_diskquota":0
      }
   ]
}

Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

A domain name, to filter the results.

If you do not use this parameter, the function returns all of the cPanel account's email addresses.

A valid domain on the cPanel account.

example.com
maxaccountsinteger

The maximum number of email addresses to return.

If you do not use this parameter, the function returns an unlimited number of email addresses.

A positive value.

500
no_diskBoolean

Whether to skip the collection of disk usage information.

This parameter defaults to 0.

Note:

We introduced this parameter in cPanel & WHM version 54.

  • 1 — Do not collect.
  • 0 — Collect.
0
no_validateBoolean

Whether to skip email database validation.

This parameter defaults to 0.

  • 1 — Skip validation.
  • 0 — Perform the validation.
0
regexstring

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

This parameter defaults to an empty string.

A valid PCRE.

For example, /^[a-z0-9_-]{6,18}$/ matches the local portion of an email address, if it contains between six and 18 characters.

/^[a-z0-9_-]{6,18}$/
emailstring

The cPanel user account to query.

If you do not use this parameter, the function returns the email addresses for all cPanel accounts that the user owns.

Note:

To retrieve information for one email address, add the domain parameter. For example, email=user&domain=example.com will return information for the email address user@example.com.

A valid cPanel account that the user owns.

 

user
infinityimgstring

An image to display for email addresses with an unlimited quota.

If you specify an infinityimg value, the function returns HTML code to display that image as the diskquota parameter's value.

The path to an image file.

images/myimg.jpg
infinitylangBoolean
Whether to return the character for email addresses with an unlimited quota.

This parameter defaults to 0.

Note:

If you specify 1 for this parameter and the infinityimg parameter, the function ignores this parameter and returns HTML code for unlimited diskquota values. 


  • 1 — Return the character for unlimited diskquota values.
  • 0 — Return the string unlimited for unlimited diskquota values.
0

Returns

ReturnTypeDescriptionPossible valuesExample
 array of hashesAn unnamed hash of data for each email address.Each hash includes the txtdiskquota, diskquota, diskusedpercent, diskpercent_float, mtime, diskused, humandiskquota, _diskused, login, email, domain, user, suspended_incoming, suspended_login, diskusedpercent20, humandiskused, and _diskquota returns. 

txtdiskquota

string

The email account's disk quota.

The function returns this value in each email address's hash.

  • A positive value that represents the email address's quota, in Megabytes (MB).
  • unlimited — The email account has an unlimited quota.
unlimited

diskquota

string

The email account's disk quota.

The function returns this value in each email address's hash.

  • A positive value that represents the email address's quota, in Megabytes (MB).
  • unlimited, ∞, or HTML code to display an infinity image — The email account has an unlimited quota. 

    Note:

    The infinityimg and infinitylang parameters determine the unlimited value for this return.

unlimited

diskusedpercent

integer

The percentage of disk space that the email account uses.

The function returns this value in each email address's hash.

  • A positive value.
  • 0 — The account has an unlimited disk quota.
0

diskusedpercent_float

floating-point

The floating-point value from which the function derives the diskusedpercent return.

The function returns this value in each email address's hash.

Note:

We introduced this return in cPanel & WHM version 68.

  • A floating-point number.
  • 0 — Unlimited or disabled disk quota.

0

mtime

integer

The email account's last modification time, in Unix time.

The function returns this value in each email address's hash.

A time, in the Unix time format.1415894498

diskused

integer

The disk space that the email account uses.

The function returns this value in each email address's hash.

  • A positive floating-point value that represents the used disk space, in Megabytes (MB).
  • 0 — The account possesses an unlimited disk quota.
0

humandiskquota

string

The disk quota, in human-readable format.

The function returns this value in each email address's hash.

  • The disk quota and the unit of measure.
  • None — The account possesses an unlimited disk quota.
None

_diskused

integer

The disk space that the email account uses.

The function returns this value in each email address's hash.

  • A positive value that represents the used disk space, in bytes.
  • 0 — The account possesses an unlimited disk quota.
483

login

string

The email address, or the main account username.

The function returns this value in each email address's hash.

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

user@example.com

email

string

The email address, or the string Main Account .

The function returns this value in each email address's hash.

  • A valid email address.
  • Main Account
user@example.com

domain

string

The email account's domain.

The function returns this value in each email address's hash.

The email account's domain.

For example, example.com if the email address is user@example.com.

example.com

user

string

The email account username.

The function returns this value in each email address's hash.

The email account's username.

For example, user if the email address is user@example.com.

user

suspended_incoming

Boolean

Whether the email account's incoming email is suspended.

The function returns this value in each email address's hash.

Note:

We introduced this return in cPanel & WHM version 54.

  • 1 — Incoming email is suspended.
  • 0 — Incoming email is not suspended.
0

suspended_login

Boolean

Whether the user's ability to log in to, send mail from, and read their email account is suspended.

The function returns this value in each email address's hash.

Note:

We introduced this return in cPanel & WHM version 54.

  • 1 — Logins are suspended.
  • 0 — Logins are not suspended.
0

diskusedpercent20

integer

The percentage of disk space that the email account uses.

The function returns this value in each email address's hash.

  • A positive value.
  • 0 — The account possesses an unlimited disk quota.
0

humandiskused

string

The disk space that the email account uses, in human-readable format.

The function returns this value in each email address's hash.

  • The disk space that the email account uses, a non-breaking space (\u00a0), and the unit of measure.
  • None — The account possesses an unlimited disk quota.
483 bytes

_diskquota

integer

The disk quota.

The function returns this value in each email address's hash.

  • A positive value that represents the disk quota, in bytes.
  • 0 — The account possesses an unlimited disk quota.
0