Email Listener – Usage and Configurations in Pega
This article is a direct continuation of our previous guide on the Email Wizard. Today, we are going to look under the hood and explore every configuration point within the Email Listener rule.
What is an Email Listener?
Simply put, an email listener monitors a configured folder within an email account. When a new email arrives, the listener picks it up and routes the message to a Service Email rule for processing.
If you were tasked with creating a new email listener right now, you would likely have a checklist of questions:
- Which account and folder do I need to monitor?
- Which service email rule handles the routing?
- How frequently should the listener check the folder?
- How do I manage the processing load (maximum messages and time limits)?
- Do we need parallel processing for better performance?
- Should I restrict the maximum email size?
- How do we handle errors for failed messages?
- What do we do with Delivery Status Notification (DSN) messages?
- How should we process email attachments?
That is exactly nine critical questions. The good news? Every single one of them can be answered by configuring the Email Listener rule form.
Accessing the Configuration Points
To follow along, open the email listener we created in the previous Email Wizard post. You can always find your existing rules by navigating to: Records -> Integration Resources -> Email Listener
Click and open the email listener rule form.
The Email Listener rule form is divided into two main tabs:
- Properties
- Process
Enjoying this content?
Access the author’s full video courses here at MyKnowAcademy.
Explore Courses →
Let’s answer our nine questions by exploring these tabs!
1. Which account and folder do I need to monitor?
(Found in the Properties tab)
Email Account: The wizard automatically populates the specified email account name. Keep in mind that the actual email address is configured within the Email Account rule form (refer to our previous article on outbound emails for more details).
Folder Name: You can specify the exact folder the listener should monitor. In most cases, this is simply INBOX.
2. Which service email rule handles the routing?
(Found in the Properties tab)
Under Service Information, you specify the unique identifiers—Service Package, Service Class, and Service Method—of the corresponding Service Email rule. Because we used the wizard, these details are pre-populated.
Note: You might notice the service method label says “Text / XML only”. While most email clients use standard text formatting, Pega also allows you to generate emails in XML or SOAP formats. If you need to process SOAP formats, you should route the message to a Service-SOAP rule instead of a Service-Email rule.
Some interesting articles below will explain in detail about email format
https://www.w3.org/TR/soap12-email/
3. How frequently should the listener check the folder?
(Found in the Properties tab)
Use the Latency period field (specified in seconds) to define the listener’s resting time. For instance, if set to 100 seconds, the listener will process the mailbox, finish routing, and then sleep for 100 seconds before checking again. The default is usually fine for most scenarios.
4. How do I manage the processing load?
(Found in the Properties tab)
To prevent your system from crashing when a massive influx of emails arrives, use these two fields:
Maximum number of messages: Defines how many emails the listener can process in one go before taking its latency nap. If you receive 1,000 emails but this limit is set to 500, the listener will process 500, sleep for 100 seconds, and then process the rest.
Maximum processing time: Similar to the above, but based on time. The listener will continuously route emails for a specified number of seconds before resting.
5. Do we need parallel processing for better performance?
(Found in the Properties tab)
In a production environment, you might have multiple nodes in a cluster. You can configure how the listener behaves across these nodes under the Listener Nodes section:
Block startup: Keep this unchecked. If selected, the listener will remain blocked after a system restart.
Startup Option: You have a few choices here:
- Run on all nodes: The listener runs across every node in the cluster.
- Node-based startup: Specify exact Node IDs where the listener should run.
- Host-based startup: Similar to node-based, but using hostnames.
- Node classification: Introduced in Pega 7.3, this allows you to map agents and listeners to specific node types (e.g., separating heavy batch-processing nodes from user-facing nodes). More about Node Classification is discussed in a separate blog article.
Concurrent threads: If the load is extremely high, you can utilize multithreading. We will cover multithreading in a future post, so leave it at 1 for now.
6. Should I restrict the maximum email size?
(Found in the Process tab)
Switching over to the Process tab! Under Read Criteria, you will find the Maximum email size (KB) field. If an incoming email (often due to large attachments) exceeds this limit, it will be marked as unprocessed.
7. How do we handle errors for failed messages?
(Found in the Process tab)
If an email fails to process (like exceeding the size limit above), you can use the Forward unprocessed messages field to send it to a system administrator’s email for debugging.
Additionally, you need to decide whether to keep processed messages on your server using the Keep messages on server checkbox. This applies specifically to the IMAP protocol.
Here is a quick refresher on the difference between IMAP and POP3:
| Protocol Feature | IMAP | POP3 |
| Storage Location | Emails reside on the server. | Emails are downloaded locally and deleted from the server. |
| Syncing | Excellent for multi-device syncing. | Poor for multi-device syncing (once downloaded, it is gone from the server). |
| Unsecured Ports | 143 | 110 |
| Secured Ports | 993 | 995 |
Recommendation: Always try to use the IMAP protocol. If you disable the “Keep messages on server” option while using IMAP, the email will be safely deleted only after it has been successfully processed.
8. What do we do with Delivery Status Notification (DSN) messages?
(Found in the Process tab)
DSN messages are auto-triggered alerts from the email server (e.g., “Mailbox full” or “Invalid email address”). You can identify these via specific header values.
If you leave the Process DSN messages box unchecked, the listener will simply discard them. However, processing DSNs can be crucial if business requirements dictate that we need to trigger fallback actions for invalid customer emails.
We will discuss handling DSN Messages in the coming blog article
9. How should we process email attachments?
(Found in the Process tab)
Under Data Options, you have three main ways to handle attachments (which are typically saved under pyAttachmentPage):
- No attachments: The listener discards attachments entirely.
- Embed data for inline images into HTML: Ensures that images embedded directly within the email body render correctly in HTML streams.
- Save original email (in EML format): Saves the raw email message as an
.emlfile attachment directly to the case. This is highly recommended for auditing and record-keeping!
Bonus Configuration: Send Email As
Before we test, there is one last configuration back on the Properties tab: Send email as. If an incoming email has multiple “To” addresses, you can use this field to configure a generic email address from which the automated reply will be sent. It supports dynamic referencing!
How to Test Your File Listener Rule
Let’s see the magic in action.
Step 1: Verify the Listener Status:
Navigate to Admin Studio and make sure the Listener is up and running..
Step 2: Check Existing Cases: Verify how many service cases currently exist in your system to establish a baseline.
Step 3: Send a Test Email: Send an email to your configured inbox (e.g., pegaknowledgesharing@gmail.com) with a recognizable subject line like “MyKnowPega check”.
Step 4: Monitor the Inbox: Confirm the email arrived in the target inbox.
Step 5: Wait for the Next Run: Wait for your configured Latency period to pass, then refresh your Pega case list. You should see a new case created just now!
Step 6: Verify Attachments: Open the newly created case. If you selected the EML option in Step 9, you will see the original email attached to the case.
Step 7: Check the Server: Go back to the email account mailbox. You should see the email is marked as read but still exists (if you kept the IMAP “Keep messages on server” setting enabled).
Step 8: Verify the Auto-Reply: Check your personal outbox to confirm you received the automated reply from the Pega system.
Cool, right? 🙂
If you want to test deleting emails from the server after processing, simply uncheck “Keep messages on server” in the Process tab, save, and test again.
Important Note: Whenever you make changes to the Listener rule form, you must restart the listener from the System Operations page for the changes to take effect!
