This guide describes how to integrate PagerDuty with any service capable of sending email alerts. Please 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 integrated with PagerDuty using our Events API.

How it Works

Events and alerts from monitoring tools will be sent as emails to your desired email address. PagerDuty will open and trigger an incident when it receives an email to this integration address.

Requirements

• This integration requires a User, Admin, Manager, Global Admin or Account Owner role to configure.
• You must have a monitoring tool that supports sending email alerts.
• You must have one of the following configured based on your integration preferences:
  • Event Orchestration: Integrating with Event Orchestrations may be beneficial if you want to build nested rules based on the events coming from the integrated tool.
  • PagerDuty Service: Integrating with a PagerDuty service directly can be beneficial if you don’t need to route alerts from the integrated tool to different responders based on the event payload.
  • Rulesets: Integrating with Rulesets may be beneficial if you want to build different routing rules based on the events coming from the integrated tool.

Integration Walkthrough

In PagerDuty

There are three ways to integrate with a PagerDuty email address:

• Event Orchestrations
• PagerDuty Service
• Rulesets

Integrate with Event Orchestrations

1. In the web app, navigate to AIOps Event Orchestration.
2. Select your desired Global Orchestration and then click Integrations.
3. To the right of the field Email Address, click Copy to Clipboard and refer to your monitoring tool’s documentation on connecting with an email address in order to complete the integration. PagerDuty will open and trigger an incident when it receives an email to this integration address. The Email Incident Example section displays a screenshot of what a test incident will look like.

Integrate with a PagerDuty Service

1. From the Services menu, select Service Directory.
2. Click the name of the service you want to add the integration to. Then select the Integrations tab and click Add an integration.
3. Search and select Email from the Select the integration(s) you use to send alerts to this service dropdown.
4. Click Add to save your new integration. You will be redirected to the Integrations tab for your service.
5. Find your integration in the list and click to the right. Copy the Integration Email address and refer to your monitoring tool’s documentation on connecting with an email address in order to complete the integration. PagerDuty will open and trigger an incident when it receives an email to this integration address.

Edit an Email Integration Address

You can customize an email integration's username in the web app:

1. Navigate to Services Service Directory and select your desired service from the list.
2. Select the Integrations tab click to the right of the email integration.
3. In the Integration Email section, click and enter a new value.

4. Click Save.

Integrate With Rulesets

❗️

End-of-Life

Rulesets and Event Rules will end-of-life on January 31, 2025. We highly recommend that you migrate to Event Orchestration as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting.

1. In the web app, navigate to AIOps Event Rules and select your Default Global Ruleset.
2. Click Incoming Event Source, copy your Email Address and then refer to your monitoring tool’s documentation on connecting with an email address in order to complete the integration. PagerDuty will open and trigger an incident when it receives an email to this integration address. The Email Incident Example section displays a screenshot of what a test incident will look like.

Email Incident Example

Below is a test incident triggered via email:

Email Management

By default, PagerDuty opens a new incident every time an email is received at the integration address. You can change this behavior by changing the Email Management setting for your service. See Trigger and Resolve Alerts with Email Management Rules for more information.

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 safelist or blocklist regular expression filter. Messages that don’t pass the filter will be silently discarded. This feature is handy if you have a monitoring tool that sends out emails that you don’t want to trigger incidents in PagerDuty. See Advanced Email Management: Extracting Information with Regular Expressions for more information on email filters.

TLS encrypted emails

PagerDuty email servers are configured to accept TLS protected SMTP sessions when your outbound mail servers are configured to use TLS opportunistically. When the message is encrypted, the last hop listed in the receive headers will mention a TLS-enabled connection.

Email Attachments and Truncation of Emails

If your email (including headers, attachments, etc.) is under 96 KB, the message can pass through without truncation. However, PagerDuty will strip all attachments from emails and truncate messages in cases where the email is over 96 KB. In those cases, the following can happen:

1. Any parts of the email body where the Content-Type is not matched by this regular expression will be discarded:
   /(text\/(plain|html)|multipart\/)/
   This means PDF files and similar attachments will be stripped.
2. Text parts (Content-Type of text/plain or text/html) will be truncated to 32 KB.
3. If the resulting total email size (including headers, attachments, etc.) still exceeds 2 MB then PagerDuty will reject the message.

You can tell if a message has been truncated or had attachments removed by checking for the headers X-PagerDuty-Truncated-Part or X-PagerDuty-Removed-Attachments when viewing the raw message. You can view the raw message on the incident's detail page by clicking View Message on an incident log entry, then View Raw Message.

See Email Notifications for more details on email content and behavior.

Email Size Limits

If an email is over 10 MB (including headers and attachments), our server will reject it. This rejection happens prior to any processing or truncation. The email server which sent the message will receive an error notification indicating that the "Message size exceeds fixed limit".

If an email is still over 2MB after truncation and being stripped of headers and attachments, it will be silently dropped and your server will not receive a notification.

Incident Key Truncation

If the incident key of the email that triggered an incident is more than 255 characters it will be truncated to 255 characters.

Truncation of Incident Details in Email Notifications

When you receive a PagerDuty email notification, the Details section of each incident will be truncated to 500 characters. That said, the entire email body is accessible in the PagerDuty web app via the incident logs and details, or via the mobile app.