Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Troubleshooting email listeners

Updated on April 6, 2022

Learn about common problems with email listeners and how to troubleshoot them.

Before reviewing the troubleshooting guidelines, you can use the following Pega Platform functionality to identify issues with email listeners:
  • Check whether there are any alerts indicating that the listener is disabled.
  • Make sure that no warnings are displayed on the dynamic system settings landing page of Pega Predictive Diagnostic Cloud (PDC).
  • Review the Log-Service-Email table for entries with the processing status Error. The table provides the reason for the error in the Error Reason column. For example, an error reason might indicate that there was an error when the system attempted to mark a message in the inbox as Deleted.

Review the following sections for troubleshooting guidance for specific email listener issues:

Email listeners fail to start

Symptoms
  • Email listeners are not marking your email messages as read.
  • Unread email messages are accumulating in your inbox.
  • The problem might be indicated by Authentication failed for listener or Failed to start listener messages in the log file.
    • OPS0034: Listener in disabled state alert is triggered in PDC. These alerts usually appear five minutes after the event began. For more information, see List of events and notifications in PDC on Pega Community.
Suggested solutions
  • Check the Startup option field on the Properties tab, which contains the property that controls how the listener starts. If the Node based startup option is selected, ensure that the correct node is added to the list. If Host based startup is selected, ensure that the correct host is added to the list.

    For Pega Cloud Services configurations, select NodeClassification based startup. Node based startup and Host based startup options are not supported for cloud-based systems because Pega Cloud Services defines the host name and node. For more information, see Configuring email listener routing.

  • Ensure that the Blocked option on the Properties tab of the listener is cleared. If this option is selected, the listener is disabled. Listeners with this setting do not start when the Pega Platform nodes start and you cannot start them from Admin Studio. For more information, see Configuring email listener routing.
  • If the service package that is configured for your email listener rule requires authentication, ensure that you provide a valid operator ID and password. For more information about service package authentication, see Defining processing and authentication for service packages.
  • If you are using the legacy Microsoft Service Management Automation (SMA) and your email listener does not respond to stop and restart commands, restart the server.
  • Ensure that the Pega-Engine prconfig/initServices/initEmail/default dynamic system setting is set to true. This setting controls whether the system initializes the Email service by default at startup. For more information, see More about Service Email rules and Configuring dynamic system settings.
    Note: This recommendation does not apply to Pega Cloud.
Important: You must restart the email listener for the preceding changes to take effect. For more information, see Restarting the email listener.

Email listeners stop running

Symptoms
  • Unread email messages are accumulating in your inbox.
  • The system is not updating existing cases or creating cases.
  • The following PDC alerts are triggered. These alerts usually appear within five minutes from when the event began.
    • OPS0036: Listener in stopped state
    • OPS0037: Number of unread emails exceeds threshold

For more information, see the List of events and notifications in PDC on Pega Community.

Suggested solutions

Email listeners stop processing emails due to throttling on the server

Symptoms

Suggested solutions
  • Increase the duration of the listener's rest period by updating the value, in seconds, of the Latency period field on the Properties tab of the email listener rule form.
  • Decrease the maximum number of messages that your listener processes per interval. You can change this configuration on the Properties tab on the email listener rule form. For more information, see Configuring email listener routing.

Email listeners take a long time to process large attachments

Symptoms
  • Large attachments are not being attached to your cases.
  • The following PDC alerts might be triggered. These alerts usually appear within five minutes from when the event began.
    • PEGA0014: Inbound mapping time exceeds limit
    • OPS0035: Number of failed messages in the last 30 minutes exceeds threshold
    • OPS0038: Average message processing time exceeds threshold
    • PEGA0119: Email listener activity time exceeds limit

For more information, see the List of events and notifications in PDC on Pega Community.

Suggested solutions
  • Ensure that the email/partialfetch (mail.imap.partialfetch) dynamic system setting is set to true. This value is recommended for best performance. This setting controls whether to use IMAP partial-fetch.
  • Set the email/fetchsize (mail.imap.fetchsize) dynamic system setting to 1 MB. This fetch size is recommended for best performance. This setting controls the size of the fetch if IMAP partial-fetch is enabled.

    For Pega Platform 8.3 and later, the default value is 1 MB. For Pega Platform versions prior to 8.3, the default value is 16 KB.

    For more information on updating the value of a dynamic system setting, see Editing a dynamic system setting.
  • Confirm the maximum email size that your email listener is configured to process by checking the value of the Maximum email size (KB) field on the Process tab of your email listener. If you specify a value in this field, the listener does not attempt to process email messages that are larger than this value.

    The value that you enter in this field overrides the value in the prconfig/services/emailMaxSize/default dynamic system setting. If you do not specify a maximum email size in this field, the email listener uses the value that is specified in the dynamic system setting.

For more information, see More about Service Email rules.

Email listeners are not processing attachments

Symptoms
  • Your email messages do not contain attachments.
  • Email attachments are not being attached to your cases.
Suggested solutions
  • Ensure that the No attachments check box on the Process tab of your email listener is cleared. For more information, see Configuring email listener processing.
  • If your application is configured to store attachments externally, verify that your repository is configured correctly. For more information, see Using file repositories.

Email listeners repeatedly fail to process the same email

Symptoms
  • Email listeners are not marking email messages as read.
  • Emails are getting stuck in your inbox.
Suggested solutions
  • Ensure that you have configured your email listener to forward unprocessed messages. For more information, see Configuring email listener routing.
  • Edit the email/maxRetry dynamic system setting to increase the number of times that the email listener attempts to retry processing the email message.
  • Use the Log-Service-Email table to determine the message ID of the failed message. Find the message in the inbox and mark the message as read.
  • Check the log files to determine the root cause of the problem.

Emails are not being attached to cases

Symptoms
  • Emails are being marked as read, but the system is not attaching emails to cases.
Suggested solutions
  • Ensure that your email listener is configured to attach emails to cases. Check the Service information section on the Properties tab of your email listener rule form.

Test connectivity of email account fails

Symptoms
  • Unread email messages are accumulating in your inbox.
  • Email listeners are unable to send autoreply messages.
  • The following PDC alert might be triggered. These alerts usually appear five minutes after the event began.
Suggested solutions
  • Ensure that the credentials that you configured on the email account are still valid.
    • In the Sender and Receiver sections of the email account form, reenter your password in the Password fields.
    • Ensure that the values in the User ID fields in both sections are identical.
    • Ensure that the Email address field in the Sender section contains the full email address.
    • Ensure that the host and port connections are valid by checking the Connection section in both the Sender and Receiver sections on the email account form.

    For more information, see Creating an email account in Dev Studio.

  • Test the connectivity of inbound and outbound email by clicking Test connectivity in the Sender and Receiver sections on the email account form. The Test Connectivity window displays the steps that the system performed to test the connection, the components it tested, and debugging information, if applicable.
  • If you are using Global Resource Settings in your email account configuration, for example, (""=D_syntax), ensure that the dynamic system settings values to which the syntax is pointing are correct. For more information, see Configuring dynamic references to external systems by using the Global Resource Settings feature.

Email listeners do not process text formatting or images

Symptoms
  • The text in an email message loses its formatting after the message is processed. For example, the numbers in an ordered list no longer appear.
  • The system creates separate attachments for each inline image in the email body and attaches each one to a case.
  • When you open a case that was created from an email, HTML tags appear in the case.
Suggested solutions
  • To ensure that email messages retain text formatting, confirm that the Handle HTML content field on the Request tab of your email service rule is set to Inline - prefer HTML.
  • Ensure that you are using a rich text editor control to display the email body in the case. For more information, see Rich text editor controls.
  • Ensure that your email server is not configured to send email messages that contain HTML tags.
  • To ensure that images appear in the email message body, confirm that the Handle HTML content field on the Request tab of your email service rule is set to Inline - prefer HTML.

    For more information, see Configuring the request for Service Email rules.

  • Confirm that the Embed data for inline images into HTML check box on the Process tab of the email listener is selected. Selecting this check box ensures that inbound email that contains inline images is rendered correctly when the email is processed.

Email listeners take a long time to stop

Symptoms
  • When you try to stop an email listener, it takes a long time to stop.
Suggested solution

Avoid stopping the email listener if it is processing multiple transactions. The email listener stops only after it finishes processing all in-flight transactions.

Email listeners take a long time to reprocess emails

Symptoms
  • Emails are marked parsing in the Log-Service-Email table.
  • The node on which the email listener is running crashes.
  • The email listener stopped running.
Suggested solutions

  • Specify the amount of time that passes before the email listener attempts to reprocess emails by creating the email/retryInterval dynamic system setting. For example, if you set the dynamic system setting to 5 minutes, the email listener tries reprocessing email messages 5 minutes after the last attempt.
    • The default value of the email/retryInterval dynamic system setting is 120 minutes.
    • Make sure to specify Pega-IntegrationEngine as the owning ruleset.

    For more information, see Creating a dynamic system setting.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us