Email Integration Guide

Introduction

This guide describes how to integrate with PagerDuty any service capable of sending email alerts. Note that we offer integration guides and plugins for many popular monitoring services. Furthermore, tools that don’t yet have dedicated guides can often be made to work with PagerDuty by using our Integration API.

Setting up PagerDuty for email integration

In PagerDuty:

  1. Click on the Services tab.
  2. On the right sidebar, click the Add New Service button.
  3. Enter a name for the service (e.g. “Critical Alerts”), select an escalation policy, and under “Integration Type” select Integrate via email.
  4. An integration email address is generated for you at the bottom, but you can change it to anything you prefer (e.g. “critical-alerts”).
    Configure the PagerDuty service
  5. Click the Add Service button.
  6. You’ll be taken to the service’s detail page. Copy the integration email to the clipboard (You’ll be using this email address to route alerts to PagerDuty).
    Copy the integration email

You just created a PagerDuty service that opens incidents when it receives email. Now you’ll just need to point your monitoring system to the integration email and you’re all set!  Below is a test incident triggered via email:

Triggered PagerDuty incident

Fine-tuning email integration

By default, PagerDuty opens a new incident every time an email is received at the integration address. Depending on how your monitoring tool works, this behavior might not be desirable. You can change when PagerDuty creates new incidents in response to emails by adjusting this service’s integration settings. To do this, click the Edit this service link on the right sidebar of the service’s detail page. In the section labeled Integration settings, you’ll see three options:

  • Open a new incident for each trigger email (default): Each email sent to the integration email address will open a new incident.
  • Open a new incident for each new trigger email subject: Emails with the same subject line will be de-duplicated. For example, if PagerDuty previously opened a new incident because it received an email with the subject “Host Down”, then a second email with that same subject will not cause PagerDuty to create a new incident. Instead, the new email will be appended to the existing incident’s activity log.
  • Open a new incident only if an open incident does not already exist: The service can have only one open incident at any time. If an email is received while the service already has an open incident, it will simply be appended to the existing incident’s activity log.
    <

Email filters

Filters allow you to disregard certain messages arriving at the integration email address. Each email’s subject, body, and from address can be checked against either a whitelist or blacklist regular expression filter. Messages that don’t pass the filter will be silently discarded. This feature is often used if a monitoring tool sends out emails when a problem has been fixed, or otherwise generates emails that shouldn’t trigger the PagerDuty alerting process.

For example, by default Pingdom will send out emails both when a host becomes unreachable, and when a previously unreachable host recovers. We can set up a filter to ensure that PagerDuty only triggers on emails indicating a host has become unreachable:

  1. Select “Accept email only if it matches ALL of the rules below” from the dropdown for the label Email filters.
  2. Select “matches the regex” for the email subject, and enter the regex “DOWN alert” in the textbox beside the dropdown.
  3. Select “matches the regex” for the from address, and enter the regex “alert@pagerduty\.com” in the textbox beside the dropdown.
  4. Click the Save changes button at the bottom to save your changes.

FAQ

Does PagerDuty keep email attachments?

Unfortunately, no, we strip all emails of attachments.  If you’d like to see this feature enabled, please email support@pagerduty.com.

Does PagerDuty limit the size of the email body?

Yes, we limit the size of the email body to 32KB.