Skip to main content


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

Troubleshooting email listeners

Updated on November 23, 2022

Troubleshoot problems with email listeners by applying the following guidelines.

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 Pega Predictive Diagnostic Cloud. These alerts usually appear five minutes after the event began. For more information, see Notification options in Pega Diagnostic Cloud 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 Service Package form - Completing the Context tab.
  • 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 Pega Diagnostic Cloud 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 Notification options in Pega Diagnostic Cloud 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 Pega Diagnostic Cloud 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

For more information, see the Notification options in Pega Diagnostic Cloud on Pega Community.

Suggested solutions
  • Ensure that the email/partialfetch dynamic system setting is set to true. This setting controls whether to use IMAP partial-fetch.
  • Set the email/fetchsize dynamic system setting to 1024000 bytes. 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 1024000 bytes. For Pega Platform versions prior to 8.3, the default value is 16 KB.

  • 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. To edit the dynamic system setting value, see Editing a 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.
  • 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 Pega Diagnostic Cloud alert might be triggered. These alerts usually appear five minutes fafter 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 (GRS) 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 How to reduce maintenance of service rules and listeners with Global Resource Settings on Pega Community.

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

When you try to stop an email listener, if the listener is processing multiple transactions, it will stop only after it completes 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