# Email Management: Filters and Rules

Use filters and create rules to customize how email integrations process events

[Email integrations](/integrations/email) allow users to integrate PagerDuty with any service capable of sending email alerts. PagerDuty provides a number of features to assist with administering email integrations, which can be broken down into the two following broad categories:

- [Email Filters](#email-filters)
- [Email Management](#email-management)

## Email Filters

Email filters allow you to determine which messages your email integration should accept. Only messages that meet your specified criteria will trigger an incident. The integration will discard any messages that do not pass the filter.

### Configure an Email Filter

To set up an email filter, in the web app:

1. Go to **Services**  →  **Service Directory** and select the service with the desired email integration.
2. Select the **Integrations** tab  →   next to the email integration you want to edit  →  click **Edit Integration**.
3. In the section **Email Filters**, make a selection from the dropdown, depending on your needs:
   - **Accept all incoming email**: PagerDuty will not filter out any emails that are sent to your integration email address.
   - **Accept email only if it matches ONE OR MORE rules below**: Emails will only be accepted if they match at least one filter rule.
   - **Accept email only if it matches ALL of the rules below**: Emails will only be accepted if they match all filter rules.
4. Configure appropriate rules:
   - The dropdowns for **subject**, **body**, and **from** default to **is anything**. Next to your desired field, select the appropriate action (**matches the regex** or **does not match the regex**) and enter a [regular expression](/incident-management/services/regular-expressions).
5. _Optional:_ If required, click **Add New Rule** and repeat the previous step to add more filtering criteria.
6. Click **Save**.

### Delete an Email Filter

1. Go to **Services**  →  **Service Directory** and select the service with the desired email integration.
2. Select the **Integrations** tab, then  next to the email integration you want to edit, then click **Edit Integration**.
3. Click  in the top right of the email filter you’d like to delete.

![Delete an email filter](/images/kb/57f9c045e59966cf0257c1c150c95db01e15f732888c1bf8fdaac1c13138fc3b-delete_email_filter.webp)

4. Click **Save changes**.

### Email Filter Example

Below is an example of how to configure email filters based on an event’s critical/noncritical status. In this example, you have a system that sends emails with the subjects `CRITICAL` and `NONCRITICAL` to PagerDuty, but you only want those with `CRITICAL` in the subject line to trigger incidents.

1. In the web app, go to **Services**  →  **Service Directory** and select the **name** of the service with an email integration.
2. Select the **Integrations** tab  →  click  to the right of the email integration you want to edit  →  click **Edit Integration**.
3. Under **Email Filters**, select **Accept email only if it matches ALL of the rules below**.
4. Add two filter rules:
   1. For the first rule, enter **The email subject matches the regex** `CRITICAL`.
   2. For the second rule, enter **The email subject does not match the regex** `NONCRITICAL`.

![Email filters for "CRITICAL" and "NONCRITICAL"](/images/kb/ef4c0050dad942eb8daba93526b65448f7947522cae8978edb8dc74ab8f01018-critical_filters.webp)

- The option **Accept email only if it matches ALL of the rules below** ensures that both rules must match with the incoming events. A second filter for `NONCRITICAL` is needed, since it contains the substring `CRITICAL`. In other words, the second rule prevents messages with the subject `NONCRITICAL` from triggering incidents, since it also matches the regex `CRITICAL`. Please also note that regex is [case sensitive](/incident-management/services/regular-expressions#case-sensitivity).

5. Click **Save changes**.

## Email Management

By default, PagerDuty opens a new incident every time an email is received at the integration address of an email integration. Depending on how your monitoring tool works and your organization’s needs, this behavior might not be desirable.

As a first step, we recommend configuring one or more [email filters](#email-filters) to ensure that your service only accepts valid email events.

When your email filters determine that an event is valid, you can use email management rules to fine tune how the events behave. For example, the email management feature allows you to create custom rules that parse inbound messages and automatically resolve incidents.

- [Configure When Incidents or Alerts Trigger](#configure-when-incidents-or-alerts-trigger)
- [Trigger and Resolve Alerts/Incidents](#trigger-and-resolve-alertsincidents)

### Configure When Incidents or Alerts Trigger

You can control when PagerDuty creates new incidents or alerts in response to emails by adjusting your email integration’s settings in the web app:

1. Navigate to **Services**  →  **Service Directory**.
2. Select the **name** of the service with the desired email integration  →  **Integrations** tab  →   to the right email integration  →  click **Edit Integration**.
3. In the section **Email Management**, select your desired setting:

- **Open a new incident/alert for each new trigger email subject** (default): Emails with the same subject line will deduplicate. For example, if PagerDuty triggers an incident in response to an email with the subject `Host Down`, subsequent emails with the same subject will _not_ trigger a new incident. You will find the new email appended to the existing _alert's_ timeline.
- **Open a new incident/alert for each trigger email**: Each email sent to the integration email address opens a new incident.
- **Open a new incident/alert only if an open incident does not already exist**: The integration will only trigger one open incident at any time. If an email is received while the integration already has an open incident (regardless of its subject line), it is appended to the existing incident’s activity log.
- **Open and resolve incidents/alerts based on custom rules**: This option is explored in-depth in the section [Trigger and Resolve Alerts/Incidents](#trigger-and-resolve-alertsincidents).

4. Click **Save**.

### Trigger and Resolve Alerts/Incidents

Selecting the option **Open and resolve alerts/incidents based on custom rules** allows you to configure rules that determine when an incident should trigger and resolve, based on the message’s content.

There are two components to configure, and both are accessed in the web app by navigating to **Services**  →  **Service Directory**  →  select the **name** of your desired service  →  **Integrations** tab  →  click  next to the desired email integration  →  click **Edit Integration**:

- [Create a Trigger Rule](#create-a-trigger-rule)
- [Create a Resolve Rule](#create-a-resolve-rule)

#### Create a Trigger Rule

1. From the dropdown, select **trigger**.
2. Select **Any (default)** or **All** depending on whether you’d like to trigger an incident when any or all following conditions match.

![Trigger rule](/images/kb/73997e66039cac3eaf8c472e6262f0094bcfd96cb368aaf91d403f57465b12e5-trigger_rule.webp)

3. **Determine the matching condition:** 
   - Select from the dropdown whether you’d like to match on the email **from address**, **subject** or **body**.
   - Select from the following matching options:
     - **contains**
     - **does not contain**
     - **matches the regular expression**
     - **does not match the regular expression**
     - **exactly matches**
     - **is anything except**
   - Enter your desired matching criteria
4. _Optional:_ If you’d like to configure more than one trigger condition, click **New Condition** and repeat step 3.
5. **Configure an incident/alert key:** It is important that this information matches in the corresponding [resolve rule](#create-a-resolve-rule).
   - In the section **Alert/Incident Key**, select **subject** or **body** from the dropdown.
   - Select from the following matching options:
     - **all text between**
     - **this regular expression**
     - **everything**
     - **all text after**
     - **all text before**

> **Use Regex to Extract an Incident/Alert Key:** If you plan to use a regular expression to generate the unique key for an incident/alert, please refer to the section [Extract an Alert Key](/incident-management/services/regular-expressions#extract-an-alert-key)  for more information.

6. _Optional:_ **Configure Custom Fields**. This feature can be helpful if your trigger emails contain information that you’d like to be included in incident details.
   - Enter a **Name** for the field.
   - **Configure the Value:**
     - Select **subject** or **body** from the dropdown.
     - Select from the following matching options:
       - **all text between**
       - **this regular expression**
       - **everything**
       - **all text after**
       - **all text before**
     - You may add more custom fields by clicking **New custom field** and repeating the steps above.
7. Click **Save changes**.

#### Create a Resolve Rule

A resolve rule is required if you’d like incidents to automatically resolve when PagerDuty receives a valid email event.

> **Auto-Resolve Using an Alert/Incident Key:** For a pair of email management [trigger](#create-a-trigger-rule) and resolve rules to work together, the alert/incident key in both rules _must be a perfect match_. The alert/incident key is what allows your service to pair events and apply resolve rules to open incidents.

1. Select **Add Another Rule** at the bottom of the page.

![Add another rule](/images/kb/edfc6fe07b4d063567829792ec4d5aec669123a85bf79b0848b3d641b09d0406-add_another_rule.webp)

2. Configure the resolve rule similarly to the [trigger rule](#create-a-trigger-rule), however you will select **resolve** from the dropdown, and configure the condition(s) that should resolve incidents/alerts. The information for **Incident/Alert Key** should _exactly_ match the corresponding trigger rule.

![Resolve rule](/images/kb/97709b857add22c7718b02f2287ade3d6b29463ecc77834933508af46c6a98ac-resolve_rule.webp)

> **No Matching Open Incident:** If an email matches your "resolve" rule but there is no open incident for that email to resolve _OR_ the email's incident key does not match an existing open incident, then this rule will not be applied.

#### Create Multiple Rules

In some cases, you may want to create more than one trigger and/or resolve rules. To do this, click **Add Another Rule**.

When you create multiple email management rules, PagerDuty will attempt to apply the first rule to the incoming email. If it does not match it will attempt to apply the second rule, and so on. The hierarchy continues in this order until it reaches your last rule. There is a limit of ten rules per service.

You can change the order rules are applied in by clicking **Move up** and **Move down** buttons on each rule.

![Move rule up or down](/images/kb/333c7ba073d974b5ac3c159998f0c38ae31d23730a13e17d03e20b136d2c2ac6-move_up_down.webp)

#### Configure Default Behavior If No Rules Match

If an email does not match any email management rules, you can configure whether you’d like to create a generic alert or discard the email.

Select your preference from the dropdown:

- **create a generic alert**
  - Generic alerts will use the email’s subject line as the name of the incident. **Note**: Email events, which _do not_ match management rules, but _do_ have matching subject lines, will deduplicate into the same alert.
- **discard it**

![Configure default behavior](/images/kb/1e06aa753333ce7986dbecf2b7373931d181e49093c9c64acdcfdb9f9b99a0f8-default_behavior.webp)

### Delete an Email Management Rule

1. Go to **Services**  →  **Service Directory** and select the service with the desired email integration.
2. Select the **Integrations** tab, then  next to the email integration you want to edit, then click **Edit Integration**.
3. Click  in the top right of the email management rule you’d like to delete.

![Delete email management rule](/images/kb/cbc72feacf674ccd055a33f2065839e0e9d181046eaf19499cf578529f7e6a49-delete_rule.webp)

4. Click **Save changes**.

### Email Management Example

In this example, you want to trigger an incident when PagerDuty receives an email (from a monitoring system, for example) that contains `DOWN` in the subject line. The body of email is always formatted such that a numeric string representing the host follows “Host: “, which can be used as the incident/alert key. We can use a [regular expression] to for this: `Host: (\d+)`.

1. [Create a trigger rule](#create-a-trigger-rule) that captures the scenario outlined above.

![Email management trigger rule](/images/kb/960159e8af016fe83a3fb80ee376d40774adf0991bebb8ebccc675ecec7fe0d0-trigger_rule.webp)

2. [Create a resolve rule](#create-a-resolve-rule)

![Email management resolve rule](/images/kb/476378464bc798c252c408778b3c8e36647e7eb09a6e8dc5842eead4a7680da0-resolve_rule.webp)

With the email management rules in place, when ​​PagerDuty receives an appropriate email that meets your trigger rule’s conditions, an incident will trigger.

![Trigger email](/images/kb/2f1642d3f7118ba27ce1a40df3259f5bdce6d894d78c88c0bc9565a6ec2a09eb-trigger_email.webp)

Similarly, when the email integration receives an appropriate resolve message, the incident will automatically resolve

![Resolve email](/images/kb/897909d3f0ae8e3b5e7153854a1651b2b30eb33a7c139fe683d7d0855acc13c4-resolve_email.webp)

## Troubleshoot Email Management Rules

Please refer to our [Email Integration Troubleshooting Guide](/integrations/email-integration-guide/email-integration-troubleshooting-guide) for helpful tips and solutions if your integration is not functioning as expected.

## Regular Expressions

Please see our [Regular Expressions](/incident-management/services/regular-expressions) article for more information.