Child pages
  • cPanel API 1 Functions - Email::addfilter
Skip to end of metadata
Go to start of metadata

Description

This function adds an account-wide email filter.

Warnings:

  • We removed this function in cPanel & WHM version 70. You cannot run this function In cPanel & WHM version 70 or later. The function will fail and it may not provide an error message.
  • cPanel API 1 is deprecated. Do not use this function. Instead, we strongly recommend that you use the following newer functions:

Examples 


 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
$new_email_filter = $cpanel->api1('Email', 'addfilter', array('This email is filtered.', 'contains', 'message_body', 'filtered@example.com') ); // Call the function.


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.
my $new_email_filter = $cpliveapi->api1('Email', 'addfilter', ['This email is filtered.', 'contains', 'message_body', 'filtered@example.com'] ); # Call the function.


Note:

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

 

 cPanel Tag System (deprecated)


Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We provide this example to help developers move from the old cPanel tag system to our LiveAPI system. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

<cpanel Module="Email::addfilter( $FORM('match value','method','msgpart','dest') )">
 Command Line
cpapi1 --user=username Email addfilter match "This email is filtered." contains message_body filtered@example.com


Notes:

  • You must URI-encode these values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to cPanel API 1 documentation or run the cpapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the cpapi1 command:

    /usr/local/cpanel/bin/cpapi1

 Output (none)

This function does not return output.

Parameters

ParameterTypeDescriptionPossible valuesExample
match value

string

or

integer

Required

The value for which to search.

Any valid string or integer.This email is filtered.
methodstring

Required

The matching type.

  • If the match value parameter is an integer, use a numeric operator.
  • If the match value parameter is not an integer, use a string operator.

Numeric operators:

  • is above
  • is not above
  • is below
  • is not below
  • equals

String operators:

  • contains
  • begins
contains
msgpartstring

Required

The email message section to search.

  • header_from
  • header_subject
  • header_to
  • reply_address
  • message_body
  • message_headers
  • h_to
  • h_cc

    Note:

    Generally, the recipient does not receive the BCC field in an email's header. For this reason, you cannot use the BCC field in a filter.

     
  • not delivered
  • error_message
  • h_X-Spam-Status
  • h_X-Spam-Score
  • h_X-Spam-Bar
message_body
deststring

Required

The destination to which the system sends email messages that match this filter's criteria.

  • Any valid email address.
  • Discard
  • A pipe to a shell application.
filtered@example.com

Returns

This function does not return output.