Creating an email service that responds to AutoReply and Delivery Status Notification (DSN) messages
Email messages sent from a Pega® Platform application can be bounced for many reasons. For example, email messages can be bounced when a recipient’s email address changed or when the operator makes a data entry error while adding a work party’s contact information that triggers a Delivery Status Notification message. Additionally, email correspondence can trigger AutoReply responses from recipients who are traveling or are on vacation.
For these reasons, it is a good practice to implement a business process that performs error handling for problem email messages and configure an email service that routes Delivery Status Notification (DSN) and Auto-Reply messages to the appropriate workbasket or work list. For example, you can configure the email service to handle emails that were addressed incorrectly differently from those that triggered an AutoReply message, you can configure the service activity to create the same kind of investigation work item for all DSN and AutoReply messages.
This article describes how to configure an email listener to route DSN messages to the email service and how to configure service activities that extract DSN information and respond appropriately to it.
DSN Information Available to the Service
When you enable an email listener to process DSN messages, the following information is available to the email service, which means you can map it to the clipboard from the Delivery Status Notification Data section on the Request tab:
- Reporting-MTA – the server that sent the message
- Action – the action performed by the Reporting-MTA in its attempt to deliver the message to the recipient address. For example: success, failed, delayed. For the complete list, see the RFC 1894 document
- Status – the DSN status code that indicates the delivery status of the message. For the list of DSN status codes, see the RFC 1893 document
- Original-text-plain – the original text of the email message in plain text
Original-text-html – if the original text used HTML formatting, the HTML of the original email message
- Original-to – the intended recipient of the message
- Original-from – the email address set in the From field of the original message
- Original-subject – the text from the subject of the original message
- Orginal-sentdate – the date the message was first sent
The Work- base class has a
Page mode property named pyInboundEmail. The page class of this property, Embed-Services-InboundEmailInfo, provides standard properties that represent the individual components of email messages including the Delivery Status Notification data listed above.
When the purpose of your email service is to manage delivery failure messages for correspondence generated during flow processing, you can use the standard properties to map email data directly to the clipboard without having to create additional properties.
Thread-Topic message header
When correspondence processing created the email message, it put the work object ID, correspondence ID, and subject into the message’s Thread-Topic message header. If the message triggers a DSN, the Thread-Topic value might still be intact, depending on the mail provider. If the Thread-Topic value is still intact, you can map the value from this header to a utility named parseThreadTopicHeader in the Message Header section on the Request tab. Be sure to specify the pyInboundEmail page property in the Map To Key field. It the Thread-Topic value is not intact, you can read it from the body of the email.
The parseThreadTopic utility processes the string in the Thread-Topic header. It extracts the values and maps them to the following standard properties:
- The complete Thread-Topic header is mapped to pyInboundEmail.pyThreadTopic
- Work object ID is mapped to pyInboundEmail.pyThreadTopicWorkID
- The correspondence (attachment) ID is mapped to pyInboundEmail.pyThreadTopicAttachID
- The subject is mapped to pyInboundEmail.pyThreadTopicSubject
These values are then located on the work page and can be displayed on the flow form for the person investigating the problem email message that triggered the DSN.
If the email listener finds the string "AutoReply" anywhere in the message, it sets the DSN Status code to 2.2.0 and then maps the Auto-Reply text as the message body.
To implement this kind of email service:
- Determine the business processes
- Create a flow that creates an investigation work object and routes it to an administrator or other appropriate workbasket.
- Run the Email wizard to create the email service and edit the results.
- Optionally, edit the the generated service activity.
Determining the business processes
Determine what your business process is for investigating DSN and AutoReply email messages, for example:
- Any DSN message, no matter what the Status code, starts a new investigation work object.
- If an email was returned with a status that indicates the mailbox is full, the associated work object could be routed back to the user who initiated the email to determine an alternate way to contact the recipient.
- If the email was returned with a status that indicates the email address is invalid, the associated work object could be returned to the operator to verify the address.
- If the email included attachments over the size limit configured on the recipient’s email system, the associated work object could be routed to a manager who examines the attached proposal and determines the best way to reduce its size.
Creating the flow
Create the problem resolution processing as appropriate for your application. For example, you could either create a new flow that generates investigation work objects, you could add a flow action to the flow that generates the outbound correspondence to route the original work object to an investigation work basket, and so on.
Running the Email Wizard and editing the results
Edit the email listener to enable DSN processing, add data mappings for the DSN fields and Thread-Topic message header in the service rule, and configure the flow to display the information about the original work object whose email message triggered the DSN.
- Follow the steps in Setting up outbound email (email account) in version 5.4 to set up the email account that manages the outbound correspondence. Make a note of the SMTP Host name that you used in the email account data object.
- Follow the steps in Setting up inbound email (email service) in version 5.4 to generate the email listener, email service, and service activity, using the following additional information:
- In the first form, select Receive an email and create a work object, even if you want the service to call a flow action for the original work object instead of creating a new investigation work object. You can edit the generated service activity to call the appropriate flow action.
- In the Email Server form, specify the same SMTP Host name that is specified in the email account data object that manages the original (outbound) email messages.
- When the wizard finishes, open the generated email listener. On the Process tab, select the Process Delivery Status Notifications (DSNs) option.
- Optional. If you want to save the email message as a work object attachment, select the Save original email option in the Data Options section. In this case, the entire email (including any embedded attachments) is treated like an attachment.
- Save the listener.
- Open the generated service rule and select the Request tab. Add a data mapping row in the Message Header section for the Thread-Topic message header. Map it to the function (Rule-Utility-Function) named parseThreadTopicHeader and enter the property .pyInboundEmail as the Map To Key. For example:
- In the Delivery Status Notification (DSN) Data section, create data mapping rows for the DSN fields that the service activity will use to route the message and that the flow is configured to display for the work object. For example:
- Select the Response tab and delete all the data mappings. (A response is not sent when the service processes a DSN.)
- Save the service rule.
Editing the generated service activity
The wizard generates a service activity that creates a work object and then attaches any email attachments (if there are any) to the work object as work object attachments. If the activity must call a flow action in the flow of the original work object rather than create a new investigation work object, select the Service tab of the service rule and specify the svcPerformFlowAction activity as the service activity.
Additionally, your service activity can evaluate the value set in the Status code property and start different flows for different Status codes or take different flow actions for different Status codes.
These procedures explain how to create a service for the purpose of managing DSN and AutoReply messages triggered by outbound correspondence. If you also have email services that create work objects from incoming emails, how should those services react if the incoming mail is a DSN?
If an email service is configured to send a response, the response message might trigger a DSN and you would not want the activity to attempt to create another work object from the DSN message. In the service activity, include a step that evaluates whether the status is empty. If the status is empty, there is no DSN information in the message and it should be processed normally.