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

 

Description

This function lists the accounts on the server.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/listaccts?api.version=1&search=username&searchtype=user
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/listaccts?api.version=1&search=username&searchtype=user
 Command Line
whmapi1 listaccts search=username searchtype=user

Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
  "data": {
    "acct": [
      {
        "mailbox_format":"mdbox"
        "inodesused":"1",
        "inodeslimit":"unlimited",
        "maxaddons": "1",
        "ip": "192.168.0.20",
        "ipv6": ["0101:ca75:0101:ca75:0101:ca75:0101:ca77"],
        "outgoing_mail_suspended": 0,
        "outgoing_mail_hold": 0,
        "min_defer_fail_to_trigger_protection": 5,
        "legacy_backup": 0,
        "diskused": "0M",
        "maxftp": "2",
        "startdate": "13 Jul 08 14:33",
        "max_defer_fail_percentage": "10",
        "disklimit": "100M",
        "is_locked": "0",
        "suspendtime": null,
        "email": "",
        "domain": "example.com",
        "unix_startdate": 1373312011,
        "user": "example",
        "plan": "plan9",
        "shell": "\/bin\/bash",
        "maxpop": "20",
        "backup": 0,
        "theme": "paper_lantern",
        "owner": "root",
        "max_email_per_hour": "100",
        "suspendreason": "not suspended",
        "maxlst": "5",
        "suspended": 0,
        "maxsql": "1",
        "maxparked": "1",
        "partition": "home",
        "maxsub": "5"
      },
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "listaccts"
  }
}
 Output (XML)
<result>
    <data>
        <acct>
         	<mailbox_format>mdbox</mailbox_format>
            <inodesused>1</inodesused>
            <inodeslimit>unlimited</inodeslimit>
			<maxaddons>1</maxaddons>
            <ip>192.168.0.20</ip>
            <ipv6>0101:ca75:0101:ca75:0101:ca75:0101:ca75</ipv6>
            <outgoing_mail_suspended>0</outgoing_mail_suspended>
            <outgoing_mail_hold>0</outgoing_mail_hold><min_defer_fail_to_trigger_protection>5</min_defer_fail_to_trigger_protection>
            <legacy_backup>0</legacy_backup>
            <diskused>0M</diskused>
            <maxftp>2</maxftp>
            <startdate>13 Jul 08 14:33</startdate>
            <max_defer_fail_percentage>10</max_defer_fail_percentage>
            <disklimit>100M</disklimit>
            <is_locked>0</is_locked>
            <suspendtime/>
            <email/>
            <domain>example.com</domain>
            <unix_startdate>1373312011</unix_startdate>
            <user>example</user>
            <plan>plan9</plan>
            <shell>/bin/bash</shell>
            <maxpop>20</maxpop>
            <backup>0</backup>
            <theme>paper_lantern</theme>
            <owner>root</owner>
            <max_email_per_hour>100</max_email_per_hour>
            <suspendreason>not suspended</suspendreason>
            <maxlst>5</maxlst>
            <suspended>0</suspended>
            <maxsql>1</maxsql>
            <maxparked>1</maxparked>
            <partition>home</partition>
            <maxsub>5</maxsub>
        </acct>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>listaccts</command>
    </metadata>
</result>

Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

   

Parameters

ParameterTypeDescriptionPossible valuesExample
searchtypestring

The account information to query.

If you do not specify a value for both the searchtype and search parameters, the function returns all of the server's accounts.

  • domain — Match domains against the search regular expression.
  • owner — Match the WHM user who owns the account against the search regular expression.
  • user — Match usernames against the search regular expression.
  • ip — Match IP addresses against the search regular expression.
  • package — Match hosting plans (packages) against the search regular expression.
domain
searchstring

A Perl Compatible Regular Expression (PCRE) that filters the results. The system matches the PCRE against the searchtype parameter's specified type.

If you do not specify a value for both the searchtype and search parameters, the function returns all of the server's accounts.

A valid PCRE.username
searchmethodstringThe function's search method.
  • exact — The matched value and the search value must be identical.
  • regex — The matched value must contain the search value.
exact
wantstring

The returns to include in the output for each account.

If you do not specify a value, the function's output includes all of its returns.

A comma-separated list of one or more of the function's returns.domain,diskused

 

Returns

ReturnTypeDescriptionPossible valuesExample
acctarray of hashesAn array of hashes of account data.Each hash includes the backup, disklimit, diskused, domain, email, ip, is_locked, legacy_backup, max_defer_fail_percentage, max_email_per_hour, maxaddons, maxftp, maxlst, maxparked, maxpop, maxsql, maxsub, min_defer_fail_to_trigger_protection, outgoing_mail_suspended, outgoing_mail_hold, owner, partition, plan, shell, startdate, suspended, suspendreason, suspendtime, theme, unix_startdate, and user returns. 

backup

Boolean

Whether backups are enabled.

The function returns this value in the acct array.

  • 1 — Enabled.
  • 0 — Disabled.
0

disklimit

string

The account's disk space quota.

The function returns this value in the acct array.

  • unlimited
  • A maximum amount of disk space, in Megabytes (MB).
unlimited

diskused

string

The account's current disk space usage.

The function returns this value in the acct array.

An integer that represents an amount of disk space, in Megabytes (MB).

For example, 14M represents 14 MB of disk space.

14M

domain

string

The account's main domain.

The function returns this value in the acct array.

A valid domainnameon the account.example.com

email

string

The account's contact email address.

The function returns this value in the acct array.

A valid email address.username@example.com

inodesused

integer

The number of files that the account owns.

Note:

We introduced this return in cPanel & WHM version 64.

The function returns this value in the acct array.

  • A positive integer.
1

inodeslimit

integer

The limit on the number of files that the account owns.

Note:

We introduced this return in cPanel & WHM version 64.

This function returns this value in the acct array.

  • unlimited
  • A positive integer.
unlimited

ip

string

The account's main domain's IP address.

The function returns this value in the acct array.

A valid IP address.192.168.0.128

ipv6

array

The account's main domain's IPv6 address

The function returns this value in the acct array.

A valid IPv6 address.
0101:ca75:0101:ca75:0101:ca75:0101:ca77

is_locked

Boolean

Whether the account is currently locked.

The function returns this value in the acct array.

  • 1 — The account is locked.
  • 0 — The account is not locked.
0

legacy_backup

Boolean

Whether legacy backups are enabled.

The function returns this value in the acct array.

  • 1 — Enabled.
  • 0 — Disabled.
0
mailbox_formatstring

The type of mailbox the account uses.

The function returns this value in the acct array.

  • mdbox
  • maildir
mdbox

max_defer_fail_percentage

string

The percentage of failed or deferred email messages that the account can send per hour before outgoing mail is rate-limited.

Note:

We introduced this return in cPanel & WHM version 11.32. 

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a percentage of messages.
unlimited

max_email_per_hour

string

The maximum number of emails that the account can send in one hour.

Note:

We introduced this return in cPanel & WHM version 11.32.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of sent emails.
unlimited

maxaddons

string

The account's maximum number of addon domains.

The function returns this value in the acct array.

  • unlimited
  • *unknown* — The account cannot use addon domains.
  • An integer that represents a number of addon domains.
unlimited

maxftp

string

The account's maximum number of FTP accounts.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of FTP accounts.
unlimited

maxlst

string

The account's maximum number of mailing lists.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of mailing lists.
unlimited

maxparked

string

The account's maximum number of parked domains (aliases).

The function returns this value in the acct array.

  • unlimited
  • *unknown* — The account cannot use parked domains.
  • An integer that represents a number of parked domains.
unlimited  

maxpop

string

The account's maximum number of email addresses.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of email accounts.
unlimited

maxsql

string

The account's maximum number of each available type of SQL database.

For example, if you set this value to 5 and the system administrator allows MySQL® and PostgreSQL® databases, users can create up to five MySQL databases and up to five PostgreSQL databases.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of SQL databases.
unlimited  

maxsub

string

The account's maximum number of subdomains.

The function returns this value in the acct array.

  • unlimited
  • *unknown* — The account cannot use subdomains.
  • An integer that represents a number of subdomains.
unlimited  

min_defer_fail_to_trigger_protection

string

The minimum number of failed or deferred messages that the account can send before outgoing mail is subject to rate-limiting.

Note:

We introduced this return in cPanel & WHM version 11.32.

The function returns this value in the acct array.

  • unlimited
  • An integer that represents a number of failed or deferred messages.
5

outgoing_mail_suspended







Boolean

Whether to suspend outgoing email from the account's users and forcefailureof any of their mail currently in the mail queue.

Note:

If mail for a cPanel user's account is suspended, the system will reject their email before the system puts it in the mail server queue.

The function returns this value in the acct array.

Note:

We introduced this return in cPanel & WHM version 56.

  • 1 — Suspend and forcefailure of outgoing email.
  • 0 — Do not suspend and forcefailure of outgoing email.
0

outgoing_mail_hold

 

 

 

 

 

 

 

 Boolean

Whether to retain outgoing mail in the mail queue for the account's users.

Note:

We introduced this return in cPanel & WHM version 56.

The function returns this value in the acct array.

  • 1 — Hold outgoing email in the mail queue.
  • 0 — Do not hold outgoingemail in the mail queue.

owner

string

The account's owner.

The function returns this value in the acct array.

  • root
  • A reseller account's username.
root

partition

string

The partition that contains the account's home directory.

The function returns this value in the acct array.

The name of a partition on the server.home

plan

string

The account's hosting package.

The function returns this value in the acct array.

The name of a package on the server.packagename

shell

string

The account's shell.

The function returns this value in the acct array.

The absolute path to a shell location on the server./bin/bash

startdate

string

The account creation date.

The function returns this value in the acct array.

The date in YY-Mon-DD HH-mm human-readable format, where:

  • YY represents the year.
  • Mon represents the month.
  • DD represents the date.
  • HH represents the hour.
  • mm represents the minute.
13 May 22 16:03

suspended

Boolean

Whether the account is currently suspended.

The function returns this value in the acct array.

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

suspendreason

string

The reason for account suspension, if one was provided.

The function returns this value in the acct array.

  • null — The account is not currently suspended.
  • A blank value, if the suspender did not provide a reason.
  • A message that explains the suspension.
not suspended

suspendtime

string

The time of suspension.

The function returns this value in the acct array.

  • null — The account is not currently suspended.
  • The time at which the account became suspended.
null

theme

string

The account's cPanel interface theme.

The function returns this value in the acct array.

  • paper_lantern
  • Another valid theme on the server.
paper_lantern

unix_startdate

string

The account creation date.

The function returns this value in the acct array.

The account creation date and time, in Unix time format.1369256589

user

string

The account username.

The function returns this value in the acct array.

A cPanel account or reseller username on the server.username