# Return account-level email filters

This function lists account-level mail filters. For more information about Exim filters, read Exim’s documentation.

Important:

  When you disable the Mail Receive role, the system disables this function.

Endpoint: GET /Email/list_filters
Version: 11.137.9999.96
Security: BasicAuth

## Query parameters:

  - `account` (any)
    The email address or cPanel account username for which to return a list of filters. If you do not specify this value, the function lists all of the cPanel account’s account-level filters.

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "list_filters"

  - `module` (string)
    The name of the module called.
    Example: "Email"

  - `result` (object)

  - `result.data` (array)

  - `result.data.actions` (array)
    An array of objects that descibe each of the filter’s actions.

  - `result.data.actions.action` (string)
    The filter’s action.

Some common ones include:

* 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.

For more information, read [Exim’s _Filter commands_ documentation](http://www.exim.org/exim-html-3.30/doc/html/filter_11.html).

  - `result.data.actions.dest` (string)
    The destination to which the filter sends mail.
* A file path.
* An application path.
* A valid email address.
    Example: "/dev/null"

  - `result.data.enabled` (integer)
    Whether the filter is enabled.

  - `result.data.filtername` (string)
    The filter’s name.
    Example: "coffee"

  - `result.data.rules` (array)
    An array of objects that descibe each of the filter’s rules.

  - `result.data.rules.match` (string)
    The filter’s match type.
    Enum: "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"

  - `result.data.rules.opt` (string)
    The connection between multiple conditions.
  * and — Match both conditions.
  * or — Match either condition.
  * null — Only one condition exists.
    Enum: "and", "or", "null"

  - `result.data.rules.part` (string)
    The queried email section.

Some common ones include:

* $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 system has not queued the message for delivery.
* error_message — Matches if the incoming message bounced.

For more options, read [Exim’s documentation](https://exim.org/exim-html-3.30/doc/html/filter.html).
    Example: "$message_body"

  - `result.data.rules.val` (string)
    The matched value. A string value.
    Example: "coconut"

  - `result.data.unescaped` (boolean)

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.status` (integer)
    * 1 — Success.
* 0 — Failed. Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.