Introduction
You can use additional parameters to filter UAPI output.
Filter output
UAPI filters use four basic parameters:
|
parameter |
Type |
Description |
Possible values |
|
api.filter |
boolean |
Whether to enable filtering. |
|
|
api.filter_column |
string |
The output parameter to match against. |
The name of one of the function's parameters. |
|
api.filter_term |
string |
The value to match. |
An integer or string value. |
|
api.filter_type |
string |
The match type.
This parameter defaults tocontains. |
Numeric operators:
Note: We introduced the ne operator in cPanel & WHM version 56. String operators:
Other operators:
Note: We introduced the defined and undefinedoperators in cPanel & WHM version 58.
|
Examples
The following example function calls execute the Email::list_lists function and filter the results to return email accounts with private mailing list archives.
cPanel or Webmail Session URL
/execute/Email/list_lists?api.filter=1&api.filter_column=archive_private&api.filter_term=1&api.filter_type=eq
LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
// List all of the mailing lists with private archives.
$private_lists = $cpanel->api2(
'Email', 'list_lists',
array(
'api.filter' => '1',
'api.filter_column' => 'archive_private',
'api.filter_term' => '1',
'api.filter_type' => 'eq',
)
);
LiveAPI Perl Class
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
# List all of the mailing lists with private archives.
my $private_lists = $cpliveapi->api2(
'Email', 'list_lists',
{
'api.filter' => '1',
'api.filter_column' => 'archive_private',
'api.filter_term' => '1',
'api.filter_type' => 'eq',
}
);
cPanel Template Toolkit
<!-- List all of the mailing lists with private archives. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column' => 'archive_private', 'api.filter_term' => '1', 'api.filter_type' => 'eq', }) %]
OutPut (JSON)
{
"messages": null,
"errors": null,
"status": 1,
"data": [
{
"listid": "mylist_example.com",
"accesstype":"public",
"desthost": "hostname.example.com",
"diskused": "17647",
"humandiskused": "17.23 KB",
"listadmin":"admin@example.com",
"list": "mylist@example.com",
"advertised": "0",
"archive_private": "1",
"subscribe_policy": "1"
}
{
"listid": "superlist_example.com",
"accesstype":"public",
"desthost": "hostname.example.com",
"diskused": "90120",
"humandiskused": "90.12 KB",
"listadmin":"charlie@example.com",
"list": "superlist@example.com",
"advertised": "1",
"archive_private": "1",
"subscribe_policy": "1"
}
{
"listid": "list1_example.com",
"accesstype":"public",
"desthost": "hostname.example.com",
"diskused": "16040",
"humandiskused": "16.04 KB",
"listadmin":"user@example.com",
"list": "list1@example.com",
"advertised": "1",
"archive_private": "1",
"subscribe_policy": "1"
}
],
"metadata": {
"transformed": 1
}
}
Use multiple filters
To use multiple filters on a single UAPI call, append an underscore (_) and a number to the end of each filter parameter.
For example, use the following parameters to pass two sets of filter information:
- Pass the first set of filter information to the
api.filter_type_0,api_filter_column_0, andapi_filter_term_0parameters. - Pass the second set of filter information to the
api.filter_type_1,api_filter_column_1, andapi_filter_term_1parameters.
Note:
Do not include more than one api.filter boolean parameter.
For example, the following examples filter the Email::list_lists function's output to mailing lists that have private archives and do not display on the Mailman directory page.
cPanel Webmail Session URL
/execute/Email/list_lists?api.filter=1&api.filter_column_0=archive_private&api.filter_term_0=1&api.filter_type_0=eq&api.filter_column_1=advertised&api.filter_term_1=0&api.filter_type_1=eq
LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once. // List all of the mailing lists with private archives that do// not display on the Mailman directory page.$very_private_lists = $cpanel->uapi( 'Email', 'list_lists', array( 'api.filter' => '1', 'api.filter_column_0' => 'archive_private', 'api.filter_term_0' => '1', 'api.filter_type_0' => 'eq', 'api.filter_column_1' => 'advertised', 'api.filter_term_1' => '0', 'api.filter_type_1' => 'eq', ) );
Live API Perl Class
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
# List all of the mailing lists with private archives that do
# not display on the Mailman directory page.
my $very_private_lists = $cpliveapi->uapi(
'Email', 'list_lists',
{
'api.filter' => '1',
'api.filter_column_0' => 'archive_private',
'api.filter_term_0' => '1',
'api.filter_type_0' => 'eq',
'api.filter_column_1' => 'advertised',
'api.filter_term_1' => '0',
'api.filter_type_1' => 'eq',
}
);
cPanel Template Toolkit
<!-- List all of the mailing lists with private archives that do not display on the Mailman directory page. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column_0' => 'archive_private', 'api.filter_term_0' => '1', 'api.filter_type_0' => 'eq','api.filter_column_1' => 'advertised', 'api.filter_term_1' => '0', 'api.filter_type_1' => 'eq', }) %]
Output (JSON)
{
"messages": null,
"errors": null,
"status": 1,
"data": [
{
"listid": "mylist_example.com",
"accesstype":"public",
"desthost": "hostname.example.com",
"diskused": "17647",
"humandiskused": "17.23 KB",
"listadmin":"admin@example.com",
"list": "mylist@example.com",
"advertised": "0",
"archive_private": "1",
"subscribe_policy": "1"
}
],
"metadata": {
"transformed": 1
}
}