Troubleshooting email listeners

Use the following guidelines to troubleshoot problems with email listeners.

Email listeners fail to start

The problem might be indicated by Authentication failed for listener or Failed to start listener messages in the log file.

  • Check the Startup option 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 desired node is added to the list. If Host based startup is selected, ensure that the desired host is added to the list.

    Pega Cloud customers should select NodeClassification based startup. Node based startup and Host based startup are not appropriate for Cloud-based startup because Pega Cloud defines the host name and node. For more information, see Configuring email listener routing.

  • If the Blocked option on the Properties tab of the listener 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 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 Microsoft SMA and your email listener does not respond to stop and restart commands, consider restarting the server.
  • Ensure that the prconfig.xml file value and the Pega-Engine prconfig/initServices/initEmail/default dynamic system setting value are set to true. This setting controls whether the Email service is initialized by default at system startup. For more information, see More about Service Email rules and Dynamic system settings.

Email listeners stop working

Email listeners take a long time to process very large attachments

  • Ensure that the email/partialfetch dynamic system setting is set to true. This setting controls whether to use the IMAP partial-fetch capability.
  • Set the email/fetchsize dynamic system setting to 102400. This setting controls the size of the fetch in bytes if the IMAP partial-fetch feature is enabled. The default is 16 KB.

For more information, see More about Service Email rules.

Email listeners process the same email repeatedly

Test connectivity of email account fails

  • Ensure that you are using the same password that you used when the email account rule was created. If the password has been changed, consider updating the password. For more information, see Creating an email account.
  • Ensure that the dynamic system settings values are correct.

The email loses its formatting after it is processed