Sending emails with "E-Mail Templates" (APEX Mail #1)

Sending emails with "E-Mail Templates" (APEX Mail #1)

Timo Herwix's photo
Timo Herwix
·

4 min read

Table of contents

Introduction

In this series we want to list step by step everything you need to know about sending emails with Oracle APEX.

Let's start with the first issue :-)

Background

Since APEX version 21.2 it is easier than ever to send emails with templates. Everything can now be configured declaratively in the APEX Builder. In the previous versions you had to use the "APEX_MAIL" API which will be discussed in the next blog post.

Let´s start by creating a demo app

Create a new application in the App Builder. In the wizard you can name your application "Email Demo" for example. Our application is now ready to add more components. The home page has no regions at the moment.

Create an email template

Let´s create an email template first. To do this, go to "E-Mail Templates" under "Other Components" of the Shared Components section.

For our newly created template, we enter the following information:

  • Template Name: Hello World

  • Static Identifier (will be generated automatically): HELLO_WORLD

  • Email Subject: Hello World

Then we can populate the HTML snippets for our template. We will use substitution strings such as #CONTACT# to pass the values to the template from our application.

Header

<H1>Hello World!</H1>

Body

<p>Hello #CONTACT#,</p>
<p>this is an email sent from <strong>Oracle APEX</strong>.</p>
<p>Best Regards</p>

Plain Text Format

Hello #CONTACT#,

this is an email sent from Oracle APEX.

Best Regards

By clicking on "Apply changes" we have created the template and can now use it in our application.

Create a "List of Values" to list all available email templates

Next, we need a "List of Values" that lists all available email templates. To do this, go to "List of Values" under "Other Components" of the "Shared Components" section and create a new LOV from scratch. For example, name it "EMAIL TEMPLATES" and set the type to "Dynamic". Then select the source type "SQL Query" and enter the following SQL statement.

select name as display, 
       static_id as return 
  from APEX_APPL_EMAIL_TEMPLATES

"APEX_APPL_EMAIL_TEMPLATES" is a predefined view from which all email templates can be selected. So with the LOV, we can now create a "Select List" of all available email templates.

Create the Home-Page

Now our application is ready to add a region, some components and a process to send emails.

First, add a "Static Content" region to your "Content Body" and name it for example "Send Email".

Then we need to have the following items:

  • P1_TO as Text Field (This will have the address of the email recipient)

  • P1_CONTACT as Text Field (This will have the name of the recipient)

  • P1_EMAIL_TEMPLATE as Select List (This contains the email template that we will send)

For the "Select List", go to the attribute "List of Values" and set the type to "Shared Component". Then select the previously created LOV "EMAIL TEMPLATE" under "List of values".

Finally, the page needs a button to send an email. So add a button "Text and Icon (Hot)" to the "Close" position. Name the button "Send" and use e.g. "fa-send" as the icon and "Send email" as the label.

When you start the application now, it should look like this.

Create a process to send the email

Next, we need a process to send an email when we hit the "Send Email" button.

Therefore, switch to Processes in the tree structure and create a new process. For example, name it "Send mail" and select the type "Send E-Mail".

Under Settings, enter the following:

  • From: &APP_EMAIL.

  • To: &P1_TO.

  • Email Template: Hello World

  • Placeholder Values: Placeholder -> Contact / Value -> &P1_CONTACT.

  • Send immediately: true

  • Success Message: Email sent

  • Error Message: Email sent failed!

  • When Button Pressed: SEND

Note! If you set "Send immediately" to true, APEX will send all emails directly. Otherwise, APEX stores unsent emails in a table and periodically delivers them for better system performance.

Let's try to send an email by clicking on the "Email send" button.

And this is how the result of the email should look like.

Conclusion

So, that's it...here is the link for the demo app.

As announced at the beginning, in the next blog post we will describe how to send email templates in previous APEX versions using the "APEX_MAIL" API.

References

orclapex