Skip to main content


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

Configuring email listener routing

Updated on April 6, 2022

Specify the email account from which the email listener pulls emails, the number of times the email listener checks the inbox for messages, and which email service rules to use for routing.

Note: If you make changes to an existing listener, stop and restart the service for the changes to take effect.
  1. In the navigation pane of Dev Studio, click Records.
  2. Expand the Integration-Resources category, and then click Email Listener.
  3. Click Create.
  4. In the Short description field, enter a short description of the listener.
  5. In the Listener name field, specify a name for this listener.
    The name is arbitrary and is only used to distinguish Email Listener instances from one another. Begin the name with a letter, and use only letters, numbers, the ampersand character, and hyphens.
  6. Click Create and open.
  7. On the Properties tab, in the Listener nodes section, configure the startup option for the listener:
    • To stop the listener from being started automatically in Pega Platform or manually in Admin Studio, select Block startup.
    • To start the listener automatically in Pega Platform and manually in Admin Studio, clear Block startup.
  8. In the Startup option field, choose from the following options:
    • To run the listener on all nodes, and all servers in a cluster, select Run on all nodes.
    • To start the listener only on specified nodes, select Node based startup and in the Node ID field, enter the node ID of the server host node or nodes where this listener runs. When a Pega Platform server starts, it activates the listener on the current node if the current node matches any node in the list (and if other requirements are met). If you specify a node, the current node must match a name in the list to activate the listener. If you do not specify a node, the listener is not activated on any node.
    • To start the listener on a specified number of nodes on specific servers within the cluster, select Host based startup. If you select this option:
      • In the Host name field, enter the network location name of the host server on which the listener starts.
      • In the Node count field, enter the number of nodes on each host server that start the listener.
    • To start the listener of specified node types, select NodeClassification based startup.
      • If you select this option, the Node Type field appears. Click the Plus icon to add another node type to the listener, then press the Down arrow key to select a node type from the list.
    • Click Reset startup to delete tracking data from the Log-Connect-AssignedNodes.
    Note: You can control when the email listener starts by using the initServices/initEmail dynamic system setting. When this setting is set to true, you can start and stop specific listeners on specific nodes from Admin Studio.
    • Owning ruleset – Pega-Engine
    • Purpose – initServices/initEmail
    • Value – true (default)

    You can also change the initServices/initEmail setting in the prconfig.xml file.

  9. In the Email Account section, enter the name of the Email Account rule that the listener references for incoming and outgoing email.
    If you do not enter an account, the rule cannot be validated when you save your configuration. You can create the rule as needed for this action.
    Note: For best performance, configure one email listener to monitor an email account. Configuring multiple listeners to monitor the same inbox can cause throttling.
  10. In the Listener properties section, in the Service information subsection, in the Service package field, configure the service parameters:
    • For email messages, enter the service package name (first key part) of the Service Email rule.
    • For SOAP messages, select the Customer Package Name (first key part) of the Service SOAP rules process arriving email messages.
    The listeners based on this data instance only process messages that identify this package; they ignore other messages.
  11. In the Service class field, enter the service class:
    • For email messages, enter the service class name (second key part) of the Service Email rule.
    • For SOAP messages, identify the second key part of the Service SOAP rules that process arriving email messages (Customer Class Name).
    The listeners process messages that identify this name (in addition to the package name) only.
  12. In the Service method (text/XML only) field, identify the service method:
    • For text or XML email messages, identify the service method key part of a Rule-Service-Email rule.
    • For SOAP messages, leave blank. For SOAP messages, the third key part to the service rule is determined in the incoming message, by the first child of the SOAP body element.
  13. In the Folder name field, enter the name of the email folder that the listener monitors, typically, INBOX.
  14. In the Latency period field, enter the duration of this listener's rest period in seconds.
    After the amount of time that you specify, the listener checks the email folder for messages. It processes all messages and then rests for this amount of time before waking up to check the inbox for messages again.
  15. In the Maximum number of messages field, enter the maximum number of messages this listener processes at run time before pausing for a rest period.
    The minimum is one message.
  16. In the Maximum processing time field, enter the maximum duration in seconds for which this listener can process messages before the system forces a rest period.
    The minimum is one second.
    Note: For all protocols except for POP3, the system continues to pull unread messages until the maximum number of messages that you specified in step 15 have been read, or until there are no more unread messages left in the folder.
  17. In the Concurrent threads field, identify the number of threads per server node that this listener requestor creates on startup.
    Note: For POP3 protocols, increasing the number of threads to more than one does not improve throughput.
  18. In the Message format field, select one of the following:
    • Text
    • XML
    • SOAP
    If you choose SOAP, the system processes incoming messages using Service SOAP rules. Otherwise, it uses Service Email rules. For more information, see Creating a Service Email rule.
  19. For incoming email messages that have more than one addressee in the To field, specify an email address to use as the From party in the Send email as field.
    When an incoming email message has only one addressee in the email To field, that same value is used as the From party of the service rule that processes the messages to generate a response.

    The value in this field overrides the value that you entered in the Send email as field in the email server data instance. This entry must be a valid email address based on your email host server settings. This field supports the Global Resource Settings syntax (=PageName.PropertyName). The default property name for this field is pyReplyAsEmail.

  20. For IMAP and Microsoft Graph protocol messages only, activate keeping messages that are received by the listener on the server by selecting Keep messages on server (Not applicable for POP3).
  21. Optional: To forward any incoming email messages that fail as an attachment to an administrator's email address, select Forward unprocessed messages.

    If this field is selected, in the Forwarding email address for unprocessed emails field, enter the email address to which you want to forward the incoming email messages that fail. This field supports the Global Resource Settings syntax (=PageName.PropertyName).

  22. If your service package requires authentication, in the Requestor login section, enter the authentication information:
    1. In the Requestor user ID field, press the Down arrow key, and then select the operator ID that the email service rule is to use when processing the email message.
      The operator ID instance for this user ID determines rulesets lists, organization, security, work queues, and so on.
    2. In the Password field, enter the password for the operator ID.
  23. If you want to view only those log messages that relate to the service rule that this listener listens for, in the Diagnostics section, enter the following information:
    1. In the Remote host field, enter the name of your workstation.
    2. In the Port field, enter the TCP/IP port number on which the log4j package on your computer listens.
      By default, this port is 8887.
    The optional Remote Logging feature streams the contents of the Pega log file to the LogFactor5 application that is installed on your workstation. Use the Admin Studio Advanced logger settings to add your workstation as an active logger. For more information, see Debugging listeners by using remote logging.
    By default, your workstation receives all messages for all processes running on the server.
  24. Click Save.
What to do next: Configure how your email listener processes email messages. For more information, see Configuring email listener processing.

Related articles

Creating an email listenerConfiguring email listener processingTroubleshooting email listeners

Tags

Pega Platform 8.7 Data Integration

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

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