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

 

Description

This function retrieves an email filter's information.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/get_filter?account=user%40example.com&filtername=coffee

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 information for user@example.com's coffee filter.
$filter_info = $cpanel->uapi(
    'Email', 'get_filter',
    array(
        'account'     => 'user@example.com',
        'filtername'  => 'coffee',
         )
);

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 information for user@example.com's coffee filter.
my $filter_info = $cpliveapi->uapi(
    'Email', 'get_filter',
    {
        'account'     => 'user@example.com',
        'filtername'  => 'coffee',
    }
);

Note:

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

 

 cPanel Template Toolkit
<!-- Get a hash of data, then display the destination value. -->
[% data = execute( 'Email', 'get_filter', { 'account' => 'user@example.com', 'filtername' => 'coffee', } ); %]
[% FOREACH q = data.dest %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the filter destination. -->
[% execute( 'Email', 'get_filter', { 'account' => 'user@example.com', 'filtername' => 'coffee', } ).data.dest %]

Note:

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

 

 Command Line
uapi --user=username Email get_filter account=user%40example.com filtername=coffee

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,
  "data": {
    "actions": [
      {
        "number": 1,
        "dest": "/dev/null",
        "action": "save"
      }
    ],
    "filtername": "FilterTest",
    "rules": [
      {
        "number": 1,
        "match": "contains",
        "part": "$header_from:",
        "opt": "or",
        "val": "example.com"
      }
  "metadata": {
    "transformed": 1
  }
}

Note:

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

   

Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

Required

The email address that owns the filter.

A valid email address on the cPanel account.

user@example.com
filternamestring

Required

The filter's name.

The name of an email filter.coffee

Returns

ReturnTypeDescriptionPossible valuesExample
actionsarrayAn array that contains a hash of the filter's actions.This array's hash contains the number, dest, and action returns. 

number

integer

The filter's position in the order of the account's filters.

The function returns this value in the actions hash.

A positive value.1

dest

string

The destination to which the filter sends mail.

The function returns this value in the actions hash.

  • A file path.
  • An application path.
  • A valid email address.
/dev/null

action

string

The filter's action.

The function returns this value in the actions hash.

  • deliver — The filter sends mail to the dest address.
  • fail — The filter forces a delivery failure.
  • finish — The filter stops message processing.
  • save — The filter saves mail to the dest file.
  • pipe — The filter sends mail to the dest application.
 
filternamestringThe filter's name.The filtername input parameter's value.coffee
rulesarrayAn array that contains a hash of the filter's rules.This array's hash contains the number, match, part, opt, and val returns. 

number

integer

The filter's position in the order of the account's filters.

The function returns this value in the rules hash.

A positive value.1

match

string

The filter's match type.

The function returns this value in the rules hash.

  • is
  • matches
  • contains
  • does not contain
  • begins
  • does not begin
  • ends
  • does not end
  • does not match
  • is above
  • is not above
  • is below
  • is not below
contains

part

string

The queried email section.

The function returns this value in the rules hash.

  • $header_from: — Matches against the From: section.
  • $header_subject: — Matches against the Subject: section.
  • $header_to: — Matches against the To: section.
  • $reply_address: — Matches against the Reply To: section.
  • $message_body — Matches against the message's body.
  • $message_headers — Matches against the message's headers.
  • foranyaddress $h_to:,$h_cc:,$h_bcc: — Matches against all message recipients.
  • not delivered — Matches if the message is not queued for delivery.
  • error_message — Matches if the incoming message bounced.
$message_body

opt

string

The connection between multiple conditions.

The function returns this value in the rules hash.

  • and — Match both conditions.
  • or — Match either condition.
  • null — There is only one condition.
or

val

string

The matched value.

The function returns this value in the rules hash.

A string value.coconut