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

Description

This function lists the mail directory's subdirectories (boxes) and files.

Important:

In cPanel & WHM version 76 and later, when you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/browse_mailbox?dir=mail%2Fexample.com



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 the mail-related subdirectories in mail/example.com.
$list_mailboxes = $cpanel->uapi(
    'Email', 'browse_mailbox',
    array(
        'dir'           => 'mail/example.com',
        )
);


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 the mail-related subdirectories in mail/example.com.
my $list_mailboxes = $cpliveapi->uapi(
    'Email', 'browse_mailbox',
    {
        'dir'           => 'mail/example.com',
    }
);


Note:

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

 

 cPanel Template Toolkit
<!-- Get a hash of data, then display the full path for each item. -->
[% data = execute('Email', 'browse_mailbox', { 'dir' => 'mail/example.com' } ) %]
[% FOREACH q = data.fullpath %]
     <p>
         [% q %]
     </p>
[% END %]
 
<!-- Get only the full paths. -->
[% execute('Email', 'browse_mailbox', { 'dir' => 'mail/example.com' } ).data.fullpath %]


Note:

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

 

 Command Line
uapi --user=username Email browse_mailbox dir=mail%2Fexample.com


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)
{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  
      "transformed":1
   },
   "data":[  
      {  
         "isleaf":0,
         "mtime":1414183324,
         "file":"archive",
         "path":"/home/user/mail",
         "depth":2,
         "relpath":"/archive",
         "ismailbox":0,
         "fullpath":"/home/user/mail/archive",
         "type":"dir"
      },
      {  
         "isleaf":0,
         "mtime":1412787616,
         "file":"example.com",
         "path":"/home/user/mail",
         "depth":2,
         "relpath":"/example.com",
         "ismailbox":0,
         "fullpath":"/home/user/mail/example.com",
         "type":"dir"
      }
   ]
}


Note:

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

Parameters

Note:

If you do not use any input parameters, the function returns a list of items in the cPanel account's main mail directory.

ParameterTypeDescriptionPossible valuesExample
accountstring

An email address, to limit the function's results.

A valid email address on the cPanel account.

user@example.com
dirstring

A mail directory name, to limit results to specific directories.

A valid directory on the cPanel account.

Note:

If you pass the default or mail values, the function lists information for all mail directories. 

maildir
showdotfilesBoolean

Whether to include hidden files and directories.

This value defaults to 0.

  • 1 — Include hidden items.
  • 0 — Do not include hidden items.
0

Returns

ReturnTypeDescriptionPossible valuesExample
mtimestringThe item's modification time.A time, in Unix time format.
1413398866
isleafBooleanWhether the item is a file or a directory.
  • 1 — File.
  • 0 — Directory.
0
filestringThe item's base name.A valid file or directory name.archive
pathstringThe item's directory's path.

The absolute path to the item's home directory.

/home/example/mail
depthintegerThe directory depth of the item's path.A positive integer.2
relpathstringThe item's relative path.The directory path to the item, relative to the mail directory./archive
ismailboxBooleanWhether the item is a mailbox.
  • 1 — Mailbox.
  • 0Not a mailbox.
0
fullpathstringThe item's absolute path.The absolute path to the item./home/example/mail/archive
typestringThe item type.
  • dir — The item is a directory.
  • file — The item is a file.
dir