• 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
• Email listeners stop running
• Email listeners stop processing emails due to throttling on the server
• Email listeners take a long time to process large attachments
• Email listeners are not processing attachments
• Email listeners repeatedly fail to process the same email
• Emails are not being attached to cases
• Test connectivity of email account fails
• Email listeners do not process text formatting or images
• Email listeners take a long time to stop
• Email listeners take a long time to reprocess emails

Email listeners fail to start

• 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.

• 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.

Email listeners stop running

• 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.

• Restart the email listener in Admin Studio. For more information, see Restarting the email listener. If you cannot restart the email listener, see the Email listeners fail to start section.
• Ensure that the requestor login credentials in your email listener rule are still valid, and reset the password or create a new operator ID. For more information, see Configuring email listener routing and Creating an operator ID.
• Ensure that the Pega-Engine prconfig/initServices/initEmail/default dynamic system setting is set to true. For more information, see Configuring dynamic system settings.
• If the these suggestions do not resolve the issue, review the log files to determine the root cause of the problem.

Email listeners stop processing emails due to throttling on the server

• Your email messages remain in the inbox, but they are not being processed or marked as read.

  Throttling is a temporary issue that is usually resolved without intervention. For more information about the symptoms of throttling in Pega Platform, see Throttling during email processing.

• Email listener requires a restart in order to listen to email messages. For more information, see Best practices for optimizing email listener performance and Throttling during email processing

• 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

• 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.

• 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

• Your email messages do not contain attachments.
• Email attachments are not being attached to your cases.

• 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

• Email listeners are not marking email messages as read.
• Emails are getting stuck in your inbox.

• 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

• Emails are being marked as read, but the system is not attaching emails to cases.

• 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

• 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.
  • OPS0029: Messages waiting in the outbound email queue exceeds threshold. For more information, see the List of events and notifications in PDC on Pega Community.

• 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

• 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.

• 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

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

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

• 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.

• 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.