Skip to main content


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

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Troubleshooting email listeners

Updated on April 5, 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.
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 Using dynamic system settings.
    Note: This recommendation does not apply to Pega Cloud.
Important: You must restart the email listener for the above 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.
Suggested solutions

Email listeners stop processing emails due to throttling on the server

Symptoms

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

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 PEGA0014: Inbound mapping time exceeds limit alert is triggered in Pega Predictive Diagnostic Cloud. These alerts usually appear within five minutes from when the event began.
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 versions 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.
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 the Pega Community article How to reduce maintenance of service rules and listeners with Global Resource Settings.

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.

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?

100% found this content useful

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