Filtering emails

The Filter property allows you to specify a filter for the probe to use when selecting emails. This property allows you specify an expression that the probe uses for matching emails. The probe only generates events for the emails that satisfy the matching the criteria, all other emails are ignored.

In the Filter property, you can specify an exact expression.

Note: The probe will not retrieve again those emails that have already been retrieved or filtered. To reset the retrieval history and thus allow probe retrieve everything currently in mailbox again, you can manually delete the file specified by RecoveryFile property while probe is stopped and then restart the probe.

Specifying an expression for exact matching in one field only

To specify an expression for exact matching in one field only, use the following format:

field_name = "field value"

Example 1

To match the text "Alert from Splunk" within the Subject field of the email, specify the following value in the ews.props file:

Filter : 'Subject = "Alert from Splunk"'

Example 2

To match the text "Alert from Splunk" in any of the fields of the email, specify the following value in the ews.props file:

Filter : 'ANY = "Alert from Splunk"'

Specifying an expression for full matching with Java Regular Expression in one field only

To specify an expression full matching with Java Regular Expression in one field only, use the following format:

field_name LIKE "java_regex"

Example 1

To match the Subject field starting with the keyword #Netcool, specify the following value in the ews.props file:

Filter : 'Subject LIKE "#Netcool.*"'

Example 2

To match a Netcool keyword in the email body, specify the following value in the ews.props file:

Filter : 'Body LIKE ".*Netcool.*"'

Example 3

To match either a Netcool or an Alert keyword starting the email body, specify the following value in the ews.props file:

Filter : 'Body LIKE "(Netcool|Alert).*"'

Example 4

To match either a Netcool or an Alert keyword starting any email field, specify the following value in the ews.props file:

Filter : 'ANY LIKE "(Netcool|Alert).*"'

Example 5

To match and process all emails, specify the following value in the ews.props file:

Filter : 'ANY LIKE ".*"'

Points to note about specifying matching criteria

Currently the probe supports matching one field only.

Either a single quote (') or a double quote (") character is used to enclose a string literal or a Java regular expression. Quotation marks are optional if the string literal contains no space.

LIKE (case-sensitive) is a special keyword that denotes the specified email field that is matched against a Java Regular Expression.

ANY (case-sensitive) is a special keyword that denotes any of the email fields. This means all fields will be scanned for fields that matches the specified criteria.

If the Filter property value is set to blank (empty string) it is equivalent to specifying the value 'ANY LIKE ".*"' which matches all emails.

The value of the Filter property is expected to be a one line specification. Any line terminator in the property value must be properly escaped with an additional backslash character (\). The correct value in this property to denote a line terminator is either \\r, \\n, or \\r\\n which includes additional leading backslash to disable un-escaping before passing to probe parser.

A DEBUG level log message is produced when an email is discarded due to a filter evaluated to false.

The following is a list of the field names most commonly used within expressions:

  • From
  • To
  • Date
  • Subject
  • Body

The following is a list of the field names that may also be used within expressions:

  • Delivered-To
  • Received
  • Sender
  • Content-Type
  • Message-ID
  • Return-Path