# cPanel API 2 Functions - Email::storefilter Warning: The cPanel API 2 system is deprecated. We **strongly** recommend that you use [UAPI](/cpanel/introduction) instead of cPanel API 2. ## Description This function creates an email filter. For more information about Exim filters, read Exim's documentation. Warning: We **strongly** recommend that you use the following [UAPI](/cpanel/introduction/) function instead of this function: - ` Email::store_filter ` — This function creates a new email filter. ## Examples WHM API (JSON) ```undefined syntaxhighlighter-pre https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=storefilter&filtername=coffee&account=user@example.com&action1=deliver&dest1=cheesecloth%40example.com&part1=%24header_subject%3A&match1=contains&val1=curds&opt1=or&part2=%24message_body&match2=is&val2=whey ``` div Note: br For more information, read our [Calls from the WHM API](/whm/use-whm-api-to-call-cpanel-api-and-uapi) documentation. br LiveAPI PHP Class ```undefined syntaxhighlighter-pre $cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Create an email filter. $create_mail_filter = $cpanel->api2( 'Email', 'storefilter', array( 'filtername' => 'coffee', 'account' => 'user@example.com', 'action1' => 'deliver', 'dest1' => 'cheesecloth@example.com', 'part1' => '$header_subject:', 'match1' => 'contains', 'val1' => 'curds', 'opt1' => 'or', 'part2' => '$message_body', 'match2' => 'is', 'val2' => 'whey', ) ); ``` div Note: br For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). br LiveAPI Perl Module ```undefined syntaxhighlighter-pre my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Create an email filter. my $create_mail_filter = $cpliveapi->api2( 'Email', 'storefilter', { 'filtername' => 'coffee', 'account' => 'user@example.com', 'action1' => 'deliver', 'dest1' => 'cheesecloth@example.com', 'part1' => '$header_subject:', 'match1' => 'contains', 'val1' => 'curds', 'opt1' => 'or', 'part2' => '$message_body', 'match2' => 'is', 'val2' => 'whey', } ); ``` div Note: br For more information, read our [Guide to the LiveAPI System](/guides/guide-to-the-liveapi-system/#guide-to-the-liveapi-system). br cPanel Tag System (deprecated) div Warnings: br - cPanel tags are **deprecated**. We **strongly** recommend that you **only** use the [LiveAPI](/guides/guide-to-the-liveapi-system) system to call the cPanel APIs. Examples are **only** present in order to help developers move from the old cPanel tag system to our [LiveAPI](/guides/guide-to-the-liveapi-system). - cPanel API 2 calls that use cPanel tags vary in code syntax and in their output. - For more information, read our [Deprecated cPanel Tag Usage](/cpanel-api-2/cpanel-api-2-deprecate-cpanel-tag-usage/) documentation. br Command Line ```undefined syntaxhighlighter-pre cpapi2 --user=username Email storefilter filtername=coffee account=user%40example.com action1=deliver dest1=cheesecloth@example.com part1=$header_subject: match1=contains val1=curds opt1=or part2=$message_body match2=is val2=whey ``` div Notes: br - You **must** URI-encode values. - `username` represents your account-level username. - You **must** run the `--user=username` command. - For more information and additional output options, read our [Guide to cPanel API 2](/cpanel-api-2/) documentation or run the `cpapi2 --help` command. - If you run CloudLinux™, you **must** use the full path of the `cpapi2` command: ```undefined syntaxhighlighter-pre /usr/local/cpanel/bin/cpapi2 ``` br Output (JSON) ```undefined syntaxhighlighter-pre { "cpanelresult": { "apiversion": 2, "func": "storefilter", "data": [ { "ok": 1, "account": "user@example.com", "error": 0, "result": "Filter Saved." } ], "event": { "result": 1 }, "module": "Email" } } ``` div Note: br Use cPanel's *[API Shell](https://docs.cpanel.net/cpanel/advanced/api-shell-for-cpanel)* interface (*cPanel >> Home >> Advanced >> API Shell*) to directly test cPanel API calls. br ## Parameters Important: For additional use information, read the [Create multiple rules](#create-multiple-rules) section. table colgroup col col col col col thead tr th strong Parameter th strong Type th strong Description th strong Possible values th strong Example tbody tr td code account td em string td p The email address, for user-level filters. p If you do not use this parameter, the function creates an account-level filter. td p A valid email address on the account. td code user@example.com tr td code filtername td em string td p strong Required p The filter's name. td p A string. td code coffee tr td code oldfiltername td em string td p An existing filter's name, to rename it. p If you do strong not use this parameter, the function creates a new filter. td A filter on the account. td code pool tr td code action* td em string td p strong Required p The filter's action. td ul li code deliver — Deliver the message to the code dest* address. li code fail — Force a delivery failure. li code finish — Stop processing the message. li code save — Save the message to the code dest* file. li code pipe — Pipe the message to the code dest* application. td code deliver tr td code dest* td em string td div p The destination for filtered mail. p div Note: br p You strong must use this parameter if the code action value is code deliver , code save , or code pipe . br td ul li A file path. li An application path. li A valid email address. td code cheesecloth@example.com tr td code match* td em string td p strong Required p The filter's a match type . ul li If the code val* parameter is a string, use a string operator. li If the code val* parameter is an integer, use a numeric operator. p br td String operators: ul li code is li code matches li code contains li code does not contain li code begins li code does not begin li code ends li code does not end li code does not match p Numeric operators: ul li code is above li code is not above li code is below li code is not below td code contains tr td code opt* td em string td p The connection between multiple conditions. td ul li code and li code or td code and tr td code part* td em string td p strong Required p The email section to query. td div ul li code $header_from: — Match against the code From: section. li code $header_subject: — Match against the code Subject: section. li code $header_to: — Match against the code To: section. li code $reply_address: — Match against the code Reply To: section. li code $message_body — Match against the message's body. li code $message_headers — Match against the message's headers. li code foranyaddress $h_to:,$h_cc: — Match against all message recipients. br p div Note: br p Generally, the recipient does strong not receive the code BCC field in an email's header. For this reason, you strong cannot use the code BCC field in a filter. br li code not delivered — Match if the message is not queued for delivery. li code error_message — Match if the incoming message bounced. td code $message_body tr td code val* td p em string p strong or p em integer td p strong Required p The value to match. td ul li Any string value. li A positive integer. td code coconut ### Create multiple rules You may create up to 4,096 separate sets of conditions in one filter. To do this, append numbers to the parameter names. To create a filter with two sets of actions and conditions, use the following parameters: - Assign the information for the first filter rule to the `action1`, `dest1`, `match1`, `opt1`, `part1`, and `val1` parameters. - Assign the information for the second filter rule to the `action2`, `dest2`, `match2`, `opt2`, `part2`, and `val2` parameters. To create a filter that uses one set of actions but two sets of conditions, use the following parameters: - Assign the actions to the `action1` and `dest1` parameters. - Assign the first set of conditions to the `match1`, `opt1`, `part1`, and `val1` parameters. - Assign the second set of conditions to the `match2`, `opt2`, `part2`, and `val2` parameters. ## Returns table colgroup col col col col col thead tr th strong Return th strong Type th strong Description th strong Possible values th strong Example tbody tr td code ok td em Boolean td Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1 tr td code account td em string td The email address or cPanel account to which the filter applies. td ul li An email address, for account-level filters. li The cPanel username, for user-level filters. td code user@example.com tr td code error td em Boolean td Whether the function encountered an error. td ul li code 1 — Errors. li code 0 — strong No errors. td code 0 tr td code result td em string td A message of success or a reason for failure. td ul li code Filter Saved. — The function succeeded. li An error message. — The function failed. td code Filter Saved. tr td code reason td em string td div p A reason for failure. p div Note: br p This function strong only returns a code reason value if it failed. br td p A string that describes the error. td code This is an error message. tr td code result td em Boolean td p Whether the function succeeded. td ul li code 1 — The function succeeded. li code 0 — The function failed. td code 1