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

 

Description

This function lists the status of a cPanel's mail account's mailboxes.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/get_mailbox_status?api.version=1&account=user@example.com
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/get_mailbox_status?api.version=1&account=user@example.com
 Command Line
whmapi1 get_mailbox_status account=user@example.com

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)
{ 
   "metadata":{  
      "command":"get_mailbox_status",
      "version":1,
      "result":1,
      "reason":"OK"
   },
   "data":{  
      "INBOX.marla_singer@example_com":{  
		 "guid":"1234560f0c58d158c92a000044f0d230",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.angel_face@example_com":{  
		 "guid":"11234560f0c58d158c92a000044f0d23",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.tyler_durden@example_com":{ 
		 "guid":"111234560f0c58d158c92a000044f0d2", 
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.Trash":{  
		 "guid":"1111234560f0c58d158c92a000044f0d",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.narrator@example_com":{  
		 "guid":"11111234560f0c58d158c92a000044f0",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX":{  
		 "guid":"111111234560f0c58d158c92a000044f",
         "vsize":"0",
         "messages":"0"
      },
      "INBOX.Sent":{  
		 "guid":"1111111234560f0c58d158c92a000004",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.Drafts":{  
		 "guid":"11111111234560f0c58d158c92a00000",
         "messages":"0",
         "vsize":"0"
      },
      "INBOX.robert_paulsen@example_com":{
		 "guid":"111111111234560f0c58d158c92a0000",  
         "messages":"0",
         "vsize":"0"
      }
   }
}
 Output (XML)
	<metadata>
		<command>get_mailbox_status</command>
		<version>1</version>
		<result>1</result>
		<reason>OK</reason>
	</metadata>
	<data>
		<INBOX.marla_singer@example_com>
			<guid>1234560f0c58d158c92a000044f0d230</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.marla_singer@example_com>
		<INBOX.angel_face@example_com>
			<guid>11234560f0c58d158c92a000044f0d23</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.angel_face@example_com>
		<INBOX.tyler_durden@example_com>
			<guid>111234560f0c58d158c92a000044f0d2</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.tyler_durden@example_com>
		<INBOX.Trash>
			<guid>1111234560f0c58d158c92a000044f0d</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.Trash>
		<INBOX.narrator@example_com>
			<guid>11111234560f0c58d158c92a000044f0</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.narrator@example_com>
		<INBOX>
			<guid>111111234560f0c58d158c92a000044f</guid>
			<vsize>0</vsize>
			<messages>0</messages>
		</INBOX>
		<INBOX.Sent>
			<guid>1111111234560f0c58d158c92a000004</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.Sent>
		<INBOX.Drafts>
			<guid>11111111234560f0c58d158c92a00000</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.Drafts>
		<INBOX.robert_paulsen@example_com>
			<guid>111111111234560f0c58d158c92a0000</guid>
			<messages>0</messages>
			<vsize>0</vsize>
		</INBOX.robert_paulsen@example_com>
	</data>

Note:

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

     

Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

Required

The email account's name.

  • A valid email account that exists on the server.
  • The cPanel user's account name.

    Note:

    _mainaccount is an alias represents the cPanel user's mailbox (For example, _mainaccount@example.com represents the example mailbox).

user@example.com

example

_mainaccount@example.com

Returns

ReturnTypeDescriptionPossible valuesExample
mailbox namehash

A hash that contains information about the mailbox's contents.

Note:

The mailbox name is the return's name.

This hash contains the guid, messages, and vsize returns. 

guid

string

The mailbox globally unique identifier (GUID).

Note:

We introduced this return in cPanel & WHM version 64.

The function returns this value in the mailbox name hash.
A valid alpha-numeric 32-byte GUID that the account owns.
1234560f0c58d158c92a000044f0d230

messages

integer

The total number of messages in the mailbox.

The function returns this value in the mailbox name hash.

A valid integer.0

vsize

integer

The total virtual size of the mailbox's contents, computed with CRLF line terminators.

The function returns this value in the mailbox name hash.

A valid integer that represents the virtual size of the mailbox, in bytes.0