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
- Ensure that the Requestor login credentials in your email listener rule are still valid. Consider resetting the password or creating a new operator ID. For more information, see Configuring email listener routing and Creating an operator ID.
- Ensure that your email server is not handling too much load or having connectivity issues. For more information, see Track system utilization for a requestor session with Performance Analyzer and System - Predictive Diagnostic Cloud.
- Ensure that Pega-Engine prconfig/initServices/initEmail/default dynamic system setting is not set to false. For more information, see Dynamic system settings.
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
- Ensure that you have configured your email listener to forward unprocessed messages. For more information, see Configuring email listener routing.
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
- Ensure that the HTML content in your email server is set to Inline - prefer text. For more information, see Configuring the request for Service Email rules.