cPanel API 1 Functions - Email::addfilter

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:
- UAPI (recommended) — Email::store_filter — This function creates a new email filter.
- cPanel API 2 — Email::storefilter — This function creates an email filter.

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

Parameter	Type	Description	Possible values	Example
`match value`	string or integer	Required The value for which to search.	Any valid string or integer.	`This email is filtered.`
`method`	string	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`
`msgpart`	string	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`
`dest`	string	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.

Function information

Module:

Email

API Version:

cPanel API 1

Available in:

cPanel version 68 and earlier.

Methods:

GET, POST

Required Parameters:

match value, method, msgpart, dest

Return Formats:

(none)

About this module

The Email module modifies cPanel email account settings.

About cPanel API 1

cPanel API 1 accesses information about cPanel accounts.

Warning:

cPanel API 1 is deprecated. We strongly recommend that you use cPanel API 2 or UAPI instead.

Notes:

These functions may require a feature list. To view the available feature lists on a cPanel server, view WHM's Feature Manager interface.
Unless you call this API via the WHM API, you must use the appropriate cPanel ports ( 2082 or 2083 ). You can also call some functions via cPanel's Webmail ports ( 2095 or 2096 ).

Find a function

Related functions

Page:

cPanel API 1 Functions - Email::adddforward — This function adds a domain-level email forwarder.
Page:

cPanel API 1 Functions - Email::addlist — This function adds a Mailman mailing list.
Page:

cPanel API 1 Functions - Email::addspam — This function enables Apache SpamAssassin™ for a cPanel account.
Page:

cPanel API 1 Functions - Email::addspamfilter — This function modifies the minimum Apache SpamAssassin™ spam score.
Page:

cPanel API 1 Functions - Email::checkpipefwd — This function checks whether a pipe or a shebang should precede a script that receives forwarded mail.

Child pages