Email providers use throttling to control the number of email messages that they receive at one time. If the number of incoming email messages surpasses a certain threshold that is determined by the email provider, the email provider might invoke throttling and drop the connection or reject additional connections.
The way that Pega Platform identifies and handles throttling depends on whether you use the Microsoft Graph, IMAP, or POP3 protocols to receive emails. For all protocols, no messages are lost or duplicated during throttling.
Microsoft Graph sends an error code to Pega Platform when throttling occurs. The error code specifies the expected duration of the throttling. Throttling is also indicated by the Application is over its MailboxConcurrency limit error message in the log file. You can view the debug message this is throttling info for additional details, such as when the throttling occurred, the retry interval, and the email account that is throttled.
When an email listener receives the error, the listener pauses email processing on all nodes on which it is running. The system also pauses sending outgoing emails from the email account that is throttled.
The email listener continues to process emails that it already read before the throttling occurred. For example, if throttling occurs while an email listener creates a case from an email, the listener continues to create the case because the listener is not required to make calls to the email provider. The email listener resumes reading emails after the throttling period ends.
Email listeners follow the same behavior as described in the Microsoft Graph section. IMAP does not send an error code when throttling occurs. Throttling is indicated by the Email Account <accountName> is getting throttled by the mail provider error message, or the javax.mail.FolderClosedException error message in the log file. When an email listener receives the error message, the listener pauses email processing on all nodes on which it is running.
If the error message does not specify a backoff time, by default, the email listener retries processing emails after 120 seconds. To adjust the default threshold, create the email/retryAfter dynamic system setting in the Pega-IntegrationEngine ruleset. For more information, see Creating a dynamic system setting.
Pega Platform includes a default pattern to evaluate error messages and determine whether the message indicates throttling. If your application displays error messages that do not match the default pattern, create the Pega-IntegrationEngine Email_throttling_pattern_regex dynamic system setting. Configure the value of the dynamic system setting to match the pattern of the throttling error message. If there are multiple error message patterns, use the | symbol to separate each pattern.
For more information, see Creating a dynamic system setting.
The email listener skips email messages during throttling and attempts to process the messages again the next time the listener wakes up.