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.

Getting started

For the purpose of this guide, we’ll integrate with Pingdom, a popular website monitoring tool that sends an email alert when a website goes down. However, these instructions can be adapted for any system that can send email alerts.

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. “Pingdom Alerts”), select an escalation policy, and under Service Type select Generic email system.
  4. An integration email address is generated for you at the bottom, but you can change it to anything you prefer (e.g. “pingdom”).
  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).

You just created a PagerDuty service that opens incidents when it receives email. Now let’s configure a monitoring system to send alerts to this service.

In Pingdom

  1. Click on the Contacts link on the left sidebar. Then click on the Add new contact button.
  2. Enter a name for the contact (e.g. “PagerDuty”). Paste the email address from the PagerDuty service (obtained from Step 6 above) into the Email field.
  3. Click Add Contact button at the bottom. This creates a new contact in Pingdom.
  4. Your new contact is now setup. You’ll now need to setup your checks in Pingdom to send notifications to PagerDuty contact. To do so, click on the Checks link on the left sidebar.
  5. Select one of your checks and click the edit icon on the right.
  6. In the section labeled Notification, select the PagerDuty checkbox for Send notification to and select the Email checkbox for Notify via.
  7. You’ll need to repeat Step 5 and 6 for all your checks.

You can manually test the email integrated PagerDuty service by sending an email to the integration email address from your favorite email client.

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.