Sending Outbound Emails from Pega

In this blog article, we will see how we can send an outbound email from a Pega application. We will start with understanding about how sending and receiving email works followed by a tutorial.

First non-Pega things. Imagine you want to send out an outbound email from your Gmail account. We just login to gmail, compose an email and then send it to receipients, but what really happens at the backend?

Think about, how physical mail processing work in the post office?

Step 1: You are in India and you write a mail to your friend in Netherlands.

Step 2: You go to post office/courier office (DHL) and post the mail. (Your job ends here)

Step 3: People working in the DHL office identifies the recipient address and the respective DHL office location (Netherlands DHL office). Then they send the mail to DHL office location may be via flight or ship.

Step 4: Netherlands DHL office receives the mail.

Step 5: The delivery person working in DHL helps with carrying the mail to the recipient address. The job ends here and your friend receives the mail 😊

Scenario: Now comeback to the electronic-mail (email), You need to send an email from your personal Gmail ID to your friend who use Yahoo ID

Let me relate the email processing with mail processing using the exact same step comparisons.

Step 1: You logged in your Gmail ID – xxx@gmail.com and sent an email to your recipient address.

Step 2: The mail reaches the SMTP email server. Here I don’t use any proxy network, so by default, It reaches the Gmail email server.

Note: There can be multiple email servers in between and they help in relaying the email message to recipients

Step 3: SMTP Email server uses DNS to identify the Email server of the recipient email address yyy@yahoo.com Yeah its Yahoo 😊. It sends the mail to recipient email server

Step 4: The recipient Email server receives the Email and they can use IMAP or POP3 protocol.

Step 5: Finally the recipient – yyy@yahoo.com receives the email using any one of the above protocol

• SMTP – protocol used for sending email
• IMAP/POP3 – protocol used for receiving email

Okay now let’s get into Pega and see how we can send an outbound email. Very first step is to configure an email account instance within Pega.

What is an Email account?

– Email account is a data instance which belongs to the Integration resources category.

– Email account instance holds the configuration details both for outbound (outgoing) and inbound (incoming) emails. It means you can configure the inbound outbound email server configurations.

In this blog article, we will concentrate only in outbound email part.

What are the pre-requisite things needed before required for you to create an outbound email account?

1. You need to have a valid email address from a valid email provider (google, yahoo etc)

2. You need to know the SMTP email server details

a) SMTP server hostname

b) SMTP server port number

What are the configurations in an email account?

First, let’s look at some of the existing email account instances and verify its configurations.

Navigate to Records -> Integration-Resources -> Email Account.

There you should see OOTB + application specific email accounts.

Make a note on the account name – Default email account. For sending out an email, we may need an Default account configured already!

What is the main advantage of having ‘Default ‘ email account?

Ideally, every email account can be tagged to a work pool (Class group). When you manually create a new email account name, make sure to use the right class name as the email account name!

But also remember it is not mandatory for every work pool to have an email account.

Say, for example, I create a Mortgage Request case in ‘MyOrg-Mortgage-Work’ Workpool. I need to send a correspondence email to the customer.

Let’s say we didn’t create any email account for the Mortgage request work pool!

Now think about how Pega handles this?  – Before sending an outbound email from a case, Pega checks If there is any email account tagged with the case work pool.

• If Yes, then Pega sends the mail from that email account.
• If No, then Pega sends the mail from the Default email account.

Default Email account can act as a base (common) email account in a Pega application.

Important note: In most of situations, you may have multiple pega applications running in a single infra stack. Default email account can be one for the entire infra stack, which means all applications may need to share it. So it advised to create a new email account for your application specific use cases!

Click and Open the ‘Default’ email account configuration.

There you see just the three blocks.

Account provider

To choose the right Email Provider. We do have list of options available in the dropdown which we will see shortly!

Here I am in Pega community edition and see the default email account is set with Custom email provider configuration.

Sender  and Receiver configurations are configured to use Office 365 configurations.

Email Address – Enter the mail ID, from which you will send the email

Display name – Enter the full name of the Sender

User ID – If there is an User ID the SMTP host use, then specify the ID there, else you can copy the  same from ‘From’ field we used above.

Password – You can specify the Office 365 User ID password.

Reply To – You can enter a valid email address, so that recipients of the outbound email can reply.

Connection

This is where you configure the details about SMTP email server

Host (SMTP) – provide the host name of SMTP email server.

What are the things to note down, when configuring SMTP Host?

The SMTP host may vary based on the network you are connected to.

Each of the email provider may have their own SMTP host. When you are inside a firewall or a closed organization make sure to check with your Operations team and provide the right Host name.

Port – Enter the SMTP server port number.

Note: To make any connection to any server, you need an open port connection.

There are three available standard SMTP ports

a) 25 – This is the default port used for transmitting mails between servers. Introduced very long back, before I came into this world.

b) 587 – This is the recommended port to be used for SMTP communication. It uses STARTTLS connection.

c) 465 – This port was introduced to support SSL means of sending email messages. But the same can be done by 587.

What port to choose 25 or 587 or 465?

a) 25 – This is still used by many email servers around the world. This is mainly used when we need to relay the emails between different email servers. The main drawback is this can be exploited to spread spam & malware

Note: If you use Organization email server(proxy network), then you need to get both the host name and port number from the administrator

b) 587 – This is highly recommended port and use STARTTLS connection. STARTTLS  can initiate a TLS/SSL connection and secure the messages. Approved by authorities.

c) 465 – This was introduced to support SMTPS connection, secured way to transmit messages but not lived up to the expectation. Still some email servers open up the 465 port for SMTPS connection. There were some fear that this port can be brought down.

Note: My advice (If no proxy network) go with 587 port to connect email servers

You can use the secure connection with STARTTLS with latest TLS version 1.2

Truststore – If your email server need to be trusted by certificates, then you can import it and trust the server using Trustore configuration.

Let’s also quickly do a test connectivity check.

The connection is perfect! Here without any new email account configurations, I can already send emails from Pega application, but this will not be the case with any Client-side implementations 😉

It is time to create our new email account for Mortgage application.

How do you configure an Email account instance?

Pega provides a simple wizard to configure an Email account.

Step 1: Navigate to Configure -> Integration -> Email -> Email Accounts

Step 2: You can use the Create button to configure a new email account or you can also just create it like other normal rule creations

Records -> Integration-Resources -> Email Account -> Create new

Make sure to use the right account name as Mortgage application class group name, so that it can be reused for all the cases within the Mortgage application. You can also specialize this for the mortgage request class!

Create and Open.

Step 3: Configure the new email account.

Account Provider

Choose your email provider from the dropdown.

The list of email providers that pega supports can vary based on Pega version!!

I will use the Microsoft Office 365 to use the Graph API.

Sender Configuration

In the sender configuration, you can choose the protocols.

You can either use SMTP protocol or Microsoft Graph to send out the email.

As soon as you choose the protocol, Pega auto-populates the send configuration details.

Identity

First, let’s fill in the Identity info

The Identity block and connection block varies based on the Email provider. We already saw with the ‘Default’ email account configuration which uses SMTP protocol, it uses certain groups of fields like email address, User ID, password and on the connections side – host and port name

But with Microsoft Graph it is just two important configurations 😊

User principal name and authentication profile.

What is Microsoft Graph?

Just look at the below picture

We know Microsoft comes with a rich suite of products with different functionalities like Sharepoint, OneDrive, Outlook etc..

Although these products are used by persons, there are also situations where they may need to be used by applications like – creating a file or sending an email.

Microsoft Graph API is a REST API endpoint that allows developers to access the Microsoft 365 services.

It acts as a bridge between the application and Microsoft 365 services and uses Azure Entra ID (formerly known as Azure AD) as the Identity and authorization service.

In the introduction, we saw most of the time we will be using SMTP protocol dedicated for sending email. But with Microsoft Office 365, we can also use REST protocol to trigger sending email via Graph API end point

Pega can connect or make use of Graph API via OAuth 2.0 authentication profile OOTB

Let’s check the steps involved.

1. Create a dummy user in Microsoft Entra ID – User Principal Name.
2. Perform an App registration in Microsoft Entra ID.
3. Provide the necessary permissions to send out an email
4. Create client credentials to use it from Pega
5. Create OAuth 2.0 Authentication profile and complete the email account configuration.

Let’s perform each of the steps.

As a pre-requisite, I already have an Azure subscription for my organization set-up.

Step 1: Create a dummy user in Microsoft Entra ID.

Note: Normally these steps will be taken care by the IAM team in the organization.

Open your Azure Entra ID resource from Portal.Azure.com and create a user.

Note: You can also use mail enabled security groups to have more control on sending email part. Please browse about it to learn more.

Once created, copy the user principal name, which we will use in the Email account configuration.

Step 2: Perform an App registration in Microsoft Entra ID

Then register your application

After registering copy the Client ID from the overview page. We will use this in the OAuth 2.0 Client credentials grant type

Step 3: Provide the necessary permissions to send out an email

You can click on the API permissions navigation and then click on Add a permission link.

This will open-up a right pop-up, where you can choose the Graph API, Application access and search for mail.

Make sure to use the below permissions – user.read (default added), mail.send, mail.readwrite

In real-time, most of the time, you will not be auto-granted. Instead, someone needs to approve and grant the permissions. Again mostly by the IAM team

For now, you can provide the grant admin consent and you should see green status on all permissions below

Step 4: Create client credentials to use it from Pega

As a last step, you can create a secret under the same registered application

On clicking add, a client secret will be created. Make a note of it.

Copy the value and not secret ID 😉

We need to use the same in the OAuth 2.0 authentication profile.

We are done with our changed in the Azure portal.

Step 5: Create OAuth 2.0 Authentication profile and complete the email account configuration

Create a new Records -> Security -> Authentication Profile -> Create new

Grant type – Client Credentials.

Client ID – Input the value we copied from step 2.

Client Secret – Input the value we copied from step 4

Scope – https://graph.microsoft.com/.default

Access token endpoint – https://login.microsoftonline.com/<tenantID>/oauth2/v2.0/token

Accept all the remaining default configurations and save the authentication profile instance.

Now, come back to the email account configuration and use the User principal name noted in step 1 and the recently created authentication profile.

Now save the Email account rule.

Click on test connectivity.

From the logs, I see some errors related to soft-deleted, not-reachable mailbox for the User principal.

I am not going into detail on the issue, So I will just use my own email ID with the Azure account and do a test connectivity.

This account is successfully configured and tested well! This should work straightaway when you try to send an email.

Let’s also finish the remaining configurations before jumping into the testing part.

Message signing

Why do we need message signing?

– The email servers help in relaying emails. If they don’t use secure connection, then there is a possibility that the email can be read by hackers or can be spoofed.

– With message signing we can encrypt and decrypt the email and transfer it securely.

How do we do it?

Step 1: You need to get the help from companies that offer digital certificates (.jks or .pfx )

Digital certificates – they are the public and private keys which can be shared only with the recipient to decrypt the email

Step 2: Create a keystore instance and upload the .jks file

Step 3: Include the keystore instance in the message signing section email account.

Now your message is digitally signed.

Note: You need to share the key with the recipient to decrypt the email.

Advanced parameters

There may be situations to modify some properties in receiving servers. You can add those parameters here.

For example, when you use Microsoft Exchange servers to receive the incoming email, you need to disable plain authentication

Key – mail.imaps.auth.plain.disable; Value – true

Note: Consult with administrators and complete it with care.

Huh! Let’s move to the next screen. Click next on the wizard

It’s time to test what we developed.

Requirement: As soon as a new Mortgage request is created, the case manager should be notified about the mortgage case creation.

Pre-requisites to test the outbound email.

a) Create correspondence rule – that can hold the email body

I created a simple correspondence rule – Mortgage case creation.

The correspondence was created of type email and also dynamic ingests the property value in the email body as shown above.

b) Case Manager Operator

Make sure you have a Case manager operator with the right email ID configured. I am using pegaknowledgesharing@gmail.com as the case manager email address.

Also for my current operator, I added the case manager operator as pyReportTo.

c) Case manager as workparty

We will send the email via OOTB activities and for that we will use the Case manager as the workparty.

I already did the configuration in the work party blog article.

Below is my configuration for the workparty configuration.

I should also see the Workparty details appended with the case on creation!

Now my pre-requisites are ready. Let’s go to the testing part.

What are the different ways to send out an outbound email?

Pega provides a lot of OOTB ways to send out an outbound email.

Advanced flow shape – send email

You can add a send email automation step from the case designer, that inturn adds the flow shape in the process flow rule.

Step 1: Add the automation shape in the Mortgage case.

Step 2: Configure the Send email step.

In the Send to, we have different options and we will use sending to Case Participants options and then choose the Case Manager.

Now the email content, You can specify the Subject and compose a custom email body directly or refer the correspondence rule directly. We will use the latter option.

You can also include the case attachments if needed.

Step 3: Test the Send email step.

Now Save the case type and create a new Mortgage request case.

As a first step, you can already the email attachment with the case.

You also see the email is received successfully in the gmail client

Before ending this blog article, let’s also understand the architecture behind this send correspondence part.

How Pega send out the outbound email?

An important thing to note is Pega always sends the email in asynchronous way so that nothing gets blocked from user portal (in case of any error).

Repeat the same steps, but just switch on the tracer at the time of sending the email.

1. Activity – SendSimpleEmail which is responsible for sending out the email.

The SendSimpleEmail activity accepts an important parameter called batchsend = true/false.

The activity step saves the correspondence instance into database table if a the email to be send via batch mode

2. Data-Corr-Email  class instance – This is where Pega saves the corr email instance

Here you can also find all the email content attached to this instance

3. Standard Agent – SendCorr, which takes care of background processing to send out the email

Make sure this OOTB agent is running from your admin studio 😊

That ends this blog article!