Service Email Usage – Handle DSN

In this final installment of our series, we will explore how to manage Delivery Status Notification (DSN) messages within Pega.

Note: This article was developed using Pega 7.4. While specific configurations may vary in newer versions, the fundamental concepts remain applicable.

Series Roadmap

To fully grasp the progression of Pega email integration, consider reviewing the articles in this order:

1. Case Creation: Generate a case from an incoming email.
2. Email Approvals: Automate case updates using Subject line data to identify the Case ID. (Current Post)
3. Conversation Management: Use Message-ID headers to link replies to cases.
4. DSN Handling: Manage delivery failures using the Thread-Topic field.

What is a DSN Message?

A Delivery Status Notification is an automated response sent by email providers for two primary reasons:

• Bounced Emails: The message failed to reach the recipient (e.g., mailbox is full, invalid address).
• Auto-replies: The recipient is out of the office or on vacation.

Note: For auto-replies, Pega typically expects the term “Autoreply” within the message. If this specific term is missing, there is a risk the message may not be identified correctly.

How to Handle DSN Messages

The primary configuration point is within the Email Listener rule form.

Step 1: Open the Email Listener and navigate to the Process tab.

If the Process Delivery Status Notifications option is unchecked, these messages will be discarded.

Let’s test this behavior:

Enjoying this content?

Access the author’s full video courses here at MyKnowAcademy.

Explore Courses →

I trace the service email rule and run the case.

In a service case “send mail” step, I input an intentionally incorrect email address.

With the setting unchecked, nothing appears on the tracer, and no processing occurs. The DSN message is left unhandled.

Why Handling DSNs Matters

Imagine a bank using Pega to service customers. If Pega sends a “late payment” email to a customer who has deleted their account, the email will continue to bounce. To handle this effectively, Pega should update the case details or notify the case owner so they can take alternative action.

Learning Pega’s Custom Email Headers

Pega sends three vital custom headers in every outbound email. You can see these in the Agent activity: Send (Class: Data-Corr-Email).

1. X-PegaWork-Handle – Contains the case pzInsKey

2. X-PegaEmail-Handle – Contains the Data-Corr-Email pzInsKey

3. Thread-Topic: A concatenation of the Case Key, Corr Key, and the Subject.

Processing the DSN Messages

Step 1: Enable DSN Processing

Switch on “Process Delivery Status Notifications” in the Email Listener rule.

Note: Always restart the listener after making changes for them to take effect.

Step 2: Map DSN Details in the Service Rule

In the Service Email rule, navigate to the Request tab. There is a specific block dedicated to DSN mapping.

Key fields available for mapping include:

• Reporting-MTA: The server reporting the DSN.
• Action: The action performed by the server (e.g., failed).
• Status: The DSN status code.
• Original…: Fields starting with “original” contain the original message information.

Pega also provides a Rule-Utility-Function to parse the Thread-Topic back into its four component fields.

Important: You must specify the Thread-Topic in the email header block of your Request tab for this mapping to function.

Testing the DSN Parsing

If you trace the rule and send mail to a junk address, you might notice the Thread-Topic data is missing.

Why is this happening? If you inspect the raw email data, you will see that some providers (like Gmail) do not include our custom headers in the DSN message itself.

If you scroll to the end of the raw data, you will see Pega correctly set the headers in the original email, but the DSN provider stripped them.

How to solve this? Refer back to Use Case 3. You can always use the Message-ID and In-Reply-To headers to identify the original email and the corresponding case. Even if headers are stripped, the DSN Status and Action values usually remain correctly mapped.

Summary of this Use Case

• DSN messages help you identify if an outbound message failed.
• Utilize the DSN block in the email request tab to collect all available failure data.
• Identify the affected case using the Subject ID (Use Case 2), Message-ID (Use Case 3), or Thread-Topic.
• Build your custom service activity to handle these failures (e.g., notifying a manager).

Important Safety Note: When creating cases via email, always either discard DSN messages or handle them very carefully. Failure to do so can result in an infinite looping scenario!

This concludes our series on Pega Email Servicing. Explore your email headers and make use of these features to build a more robust integration!