Skip to main content

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

More about Service Email rules

Updated on November 23, 2022

Email conversations

The standard Service Email rule EmailDefault.Work-.CreateEmailFlow (and the associated service activity Work-.ProcessInboundEmail ) support email conversations. When appropriately configured, each email correspondence contains a unique identifier (in the message header) associated with the originating work item ID. A reply to that email also contains that ID. The ProcessInboundEmail activity attaches the email to the work item.

Email-based work processing

You can perform approvals or other actions on work items using email-based work processing. You can configure the application to send an approver an email that contains hyperlinks to non-local flow actions. The approver can click the appropriate flow action, then send the response. An email listener validates the response and creates a work item using the service activity pyCreateAndManageWorkFromEmail, then delegates processing to the pyProcessEmailRequest agent.

Standard properties for data mapping the request

The Work- base class has a Page mode property named pyInboundEmail. The page class of this property, Embed-Services-InboundEmailInfo, provides standard properties that represent the individual components of email messages: to, from, subject, body, date, and so on. When the purpose of your email service is to create new work items or to manage delivery failure messages for correspondence generated during flow processing, you and the Email Wizard can use these standard properties to map email data directly to the clipboard without having to create additional properties.

When you use the accelerator to generate email services, it configures the following inbound mappings:

  • The value of the To field is mapped to .pyInboundEmail.pyTo
  • The value of the CC field is mapped to .pyInboundEmail.pyCC
  • The value of the From field is mapped to .pyInboundEmail.pyFrom
  • The value of the Subject field is mapped to .pyInboundEmail.pySubject
  • The message data is mapped to .pyInboundEmail.pyBody

You can also use . pyInboundEmail.Date for mapping the value from the Date field.

Standard properties for data mapping DSN data

The Embed-Services-InboundEmailInfo class also provides standard properties that represent the individual components of Delivery Status Notification messages. You can use the following standard properties to map DSN data directly to the clipboard without having to create additional properties:

  • .pyInboundEmail.pyAction
  • .pyInboundEmail.pyOriginalFrom
  • .pyInboundEmail.pyOriginalSentDate
  • .pyInboundEmail.pyOriginalSubject
  • .pyInboundEmail.pyOriginalTextHTML
  • .pyInboundEmail.pyOriginalTextPlain
  • .pyInboundEmail.pyOriginalTo
  • .pyInboundEmail.pyReportingMTA
  • .pyInboundEmail.pyStatus

Standard HTML rules for data mapping the response

When the service activity is finished with its processing, the email service sends the response configured on its Response tab through the email listener. If another email message is sent at a later point in the flow processing, that message is managed by an outbound email account and not by the email listener.

The Work- base class has two standard HTML rules that you can use for the service rule’s response:

  • EmailHeader, which provides the text from the original email subject ( .pyInboundEmail.pySubject ). You can use it to provide the value for the Subject field in the response.
  • EmailResponse, which is a simple thank you message that provides the work item ID for the new work item (created by the service processing) and includes the message data from the original email. You can use it to provide the text for the message body.

When you use the Email Accelerator to generate email services, it uses these standard HTML stream rules in the response. You can edit the stream rules or change the outbound mapping as necessary.

Attachments to incoming email

If an incoming email message contains attachments, the email listener creates a page named pyAttachmentPage of class Data-ServiceMessage and puts the attachments on that page. When you use the Email Wizard to create an email service that creates work items, the generated service activity automatically extracts the files from the pyAttachmentPage and uses them as work item attachments.

If you create an email service without using the Wizard, and you want the service to use the attached files as work item attachments, configure the service activity to handle work items. For information, see Pega Community article How to save an incoming email message as a work item attachment using Email Service rules.

To test arriving email attachments for software viruses, override the extension point activity Data-WorkAttach-File.CallVirusCheck with an activity that calls your third-party virus software. Your activity can call a Java class or (in a Microsoft Windows server) a Dynamic Linked Library routine.


To test outbound email, run through the entire flow and then verify that notify and other email messages are delivered the way you expect them to be.

To test inbound email, start with the listener. From the listener form, click the Test Connectivity button to ping the email server. Then use Admin Studio to verify that the listener is running. Open the email service rule and use the Run Rule feature to run it. Finally, from the external application, send a request message to the inbox monitored by the email listener. Then check the inbox of the external application to determine whether the response message arrived and whether it contains the information you expected.

See also the Pega Community document Testing Services and Connectors for information.

Email dynamic system settings

You can use the following Pega Platform dynamic system settings to modify the behavior of email processing on your system:

Services/EmailMaxSize Limits the maximum size in KB for an email message. Enter -1 to allow messages of any size.

This value is overridden by the Maximum Email Size (KB) field on the Process tab of the Email Listener data instance.

Services/EmailSuppressUnknownContentErrorIf true, suppress any unknown content type errors.
Services/EmailSuppressMailAPILoggingIf true, suppress any API debugging messages.
email/timeoutConnection timeout for SMTP
email/fetchsizeControls size of fetch in bytes if IMAP partial-fetch feature is enabled. Default is 16 KB. Typically does not need to be reset.
email/partialfetchControls whether to use the IMAP partial-fetch capability. Defaults to true. Typically does not need to be reset.
email/blockResponseIf true, all responses are blocked. No response will be sent.
email/enableTextAttachmentInEmailBodyIf true, text attachments can be embedded in the Email body.
prconfig/initServices/initEmail/defaultControls whether the Email service is initialized by default at system startup. The default for the setting is true. In a multinode system, this setting allows you to control whether the Email service is available on individual nodes.

If set to true, ensures that message processing failures are caught. If set to false, ignores processing failures related to message headers. The default setting is true.

Performance logging

You can collect performance statistics about the resources used by a service in a Comma-Separated-Values (CSV) file, accessed from the Log menu. See Performance tool — Statistics for services in the SERVICES-PAL log.

Email Service Sample

An email service sample is provided to demonstrate an out-of-the-box self-contained example for application designers to configure. Sample rules are stored in the Pega-LP-Integration RuleSet under the root class PegaSample-Integration derived from the PegaSample class. Please refer to the Pega Community.

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?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us